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You can too 


Revolution^” 

The Solution for Software Development 

In enterprise>.,business and education 


REVOigTIOII 

Limitless possibilities 

With Revolution, the solutions you can create 
are endless. 

True cross-platform development 

With the click of a button, you can build 
applications for Macintosh (Classic and OS X), 
Windows, Linux, and Unix. 

Increased productivity 

The powerful interface builder and easy-to-use 
programming language speed up all the 
essentials of software development, leaving you 
with more time to focus on your project. 

Databases, multimedia, Internet applications, 
external libraries and more 

Revolution supports everything you need: SQL 
databases, streaming media, control of 
QuickTime, QTVR and graphics, CGI processing, 
Internet protocols, and more. 

FREE Trial Version 

www.runrev.com 
















YOUR DATABASE SERVER WITH THE 

C-TREE SERVER SDK 



Today’s dalabasc demands are often loo complex for tradiuonal database servers. 
The functionality and precise level of control you need is simply not available. 
Perhaps you need alternate sort criteria for your data or a special twist in the 
threading or communication logic. 

FairCom’s c-irce* Server SDK allows you to create a customized, 
industrial-strength server designed for your particular needs. Use 
FairCom’s kernel, with over 20 years of proven stability, or override 
functionality within spccillc subsystems to implement your own 
subtleties. Move your application’s data I/O functions to the 
server-side to decrease network traffic and increase performance! 

FairCom’s c-tree Server SDK is used by companies worldwide 
such as Software AG and Citibank'"* It’s integrated 
seamlessly into c-tree Plus and includes complete source 
code to the server mainline and all the interface 
subsystems to the c-tree Server. And best of all, once 
you’ve created your unique, customized server, 
it is easy to install and atl mini star: no DBA 
required! 


• Fnliance our server with your own 
custom server-side functiimalily 

• Move funclionality from tbe client-side to 
the sei*ver-side to reduce network LraHlc 
and increase performance 

• Modify or replace entire server 
subsystems 

■ Complete source for the server 
mainline, key server 
subsystems, and client-side 

• Flexible ORM licensing 


Visit www.faircom.com/ep/mt/sdk today to take control of your server! 


USA 
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EUROPE 

+39.035,773.4ri4 
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JAPAN 

+«1.59.229,7504 

www.faircam.com 
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(FOR AN ENTERPRISE CLASS DATABASE.) 


An insanely great enterprise server deserves an insanely great enterprise database. Sybase Adaptive 
Server'” Enterprise 12.5. Wall Street's preferred platform for mission-critical, transaction-intensive 
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THE CALL. 


enterprise applications. Now available to you on Apple Xserve* with Mac OS X 
Server software. Ready to scream for joy? Check it out at www.sybase.com/mac 

Information Anywhere 
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^ Sybase 




SylMiw, Inr All rNphiH All Itadf marks a nr (hr property uf ihetr r&pectlvu uwitos. 












7he JcmrrmI of Madnki&h Techrmh^^^ & Det^kipmmU 


A publication of XPIAIH CORPORATION 


HctwTo ConiniunicateWith Us 


Tn this electronic age, the art of 
communication has become both easier 
and more complicated. Is it any surprise 
that we prefer e-mail? 

If you have any questions, feel free to call us 
at m5/W-9797 or fax us at 805/49^-9798. 

If you would like a siibscripiion or need 
customer service, feel free to contact 
Developer Depot Customer Servk:e at 
877-MACTHCIl 


DEPABrmFKIS 

K-Mall/CRI, 

Orders, Circulation, & Customer Service 

cust_sen^ice@ mactech .com 

Press Releases 

jxesjs_Telea.ses#niacl:ec h .ooni 

Ad Sales 

ad_sale5@maciecli .com 

Editorial 

editorial@mactech .com 

Programmer's Challenge 

pn;)gjclxillenge@mactech .com 

OnlfiK Support 

online@mucicch.com 

Accounting 

;iccDunting@niactech .com 

Marketing 

jTiii!kcting@niactcch .com 

Cicticral 

info@mdctech.axia 

Vl4eb Site (aitkks, info, URLs and iiiore,«) 

htip;//ww w. madeclLcom 


7 he Macl'eeb Tidiiotial Maff 
Publislier • NeiJ Tickiin 
Ediior-iii-Chicf • l>ave Mark 
Managing Editor • je.ssica Stuhhleheld 

Regular Coluntnists 
Getting Started 
by Dave Mark 
QuickTime TooIKit 
by i iin Momoe 
Reviews/KoolTooLs 
l^y Michael K. Harvey 
Networking 
by John C Welch 
Section 7 
by Rich Morin 

RegiiUir Contributors 

Vicki Brown, Andrew Stone, 

Erick Tejkowski, Paul E. Sevinc 

Mtu:7evb*s Ikmrd of Adifisors 

Jordan LX'a-MatLson, Jim Siraiis 
and Jon W'iedcrspan 


latTtxh’s Contribtiluig Editors 

Michael Brian Bemley 
Marshall Glow 
John. C. Dau[> 

'Ibm Djajadiningrar 
Bill Doerrfeld, Blue world 
Andrew S. Downs 
Richard V. Ford, PacketecT 
(iordon Gari>, Sun 
llene Hoffman 

Chris Killx>urn, Digital Forest 
Rich Morin 

Joiin OTalkrn, Maxuru Deveioi)meiii 
Will Porter 

Avi Rappo|x>rE Search Tools Consul ling 
Ty Shipman, Kagi 
CliLick Shoium, BlAP Systems 
Cal Simone, Main Event Software 
Steve Sisak, Codewell Corporation 
Andrew C. Stone, www.stone.coni 
Chuck Von Rospach, Plaidworks 
John C. Welch 


Xfjfaiit Cffrporaiion Staff 
Chief Executive Officer * Neit Ticktin 
Prcsidcat * Andrea j. Sniderman 
OintroUcr • Michael Friedman 
Prodiietioo Manager • Jessira Stubble field 
Production/Layout * Darryl Smart 
Marketing Manager • Nick DeMello 
Events Manager • Susitn M. VCbrIey 
Iiiternatioual • Rose Kemps 
Network Administrator * David Biefl'itt 
Accounting * Jan Webber, Marcie Moriany 
Customer Relations • Laura Line 

Susan Pojnranis: 

Shipping/Recciving • |oeI Licardie 

Hoard of Advisors • Sreven Gel let; Blake F^ark, 
and Alan Carsiud 


All c’t>nrenrs Arv Q>pyiight f9^^4-2002 h^^ Xplain Oorpnririon. 
AD ivserv'ctl. MacTed] ynti lX'vdo|Kr Ot-ptM aitf 

(ivgbtefetl iratbtrirks nf Xphin (brpfinitkjrv HadGicL Useful 
OiifiH uad Gadgets, Xplain, IXvOeptiL tX"|XH. live iXfXiL, 
IX^pit Stone, Vickx) IX^ptx, Movr IX^pni. Piilm IV|Xit, Giime 
1X^|X)C llasliliKhi tXfixa, liXpliiiii li, MaeDwd, IIIINK 
Mdcieixv. NetProfessbnyL HciFtoUvc. Jnv“iTcch, iSA’hTceh, 
IJeTecti, liniJxTedi, Miic'l'edi Central asxl t!ie MitcTuiorMin 
are tn<!f:’iicirk.s (ir scrvke markH nf Xplain DjrptirJtinn, 
Sprocket ii* d tegisiered tradetrurk d eSpriKkei Co^xiniUoir 
Otlx^r trjdcnnirks and topyrigliis appeimag in this jxinting or 
sokwatv icirKiin the properly of tlw^ir reiipeclive lK>iden>. 


MacTech Magazine (ISSN: 1067-8360 / USPSi 010-227) is published montlily by Xpkin Ca^qxiration, 850-P Hampshire Road, Westlake Village, CA 93361- 
2800. Voice: 805/494-9797, FAX: 805/494-9798, Domestic stibscripiion mtes are $47,00 per year. Canadian sub^riptions arc $59.(X) per yc^at All other 
international .sLiliscriptioas are $97.00 y>er yetir. Domestic souice cxxle disk suKscriptioas are $77 per year. All intemnitional disk SuliscripUons ate $97,00 a ye^ir. 
idease remit in U.S. funds only* Periodical postage is paid at Tliousand Oaks, CA and at additional mailing offic'e. 

POSTMASTER! Send address changes to MacTech Magazine, P.O. Box 5200, WesUake Village, CA 91359-5200. 


Tmk Staff 


MacTech • Ja.ni:ary 2003 


























Contents 


January 2003 • Volume 19, Issue 1 

Mac 05 X 

CamelBones 

42 Creating CUl-based apps with Peti 
By Rich Morin 


QuickTime Toolkit 

24 

Animal Crackers 

Enhancing Cocoa QuickTime Appfkations 
by Tim Monroe 


Getting Started 

6 A Taste of Project Builder 

by Da\/e Mark, Editor in Chief 


Mac os X 


Section 7 

still More Perl 

Munging Mail and Media.., 
by Rich Morin 


Writing Contextual Menu Plugins for OS X, part 2 

Running Unix commands and handling tejtf selections 

By Brent Simmons 


Handheld Technologies 

TicTacPalm 2 

^ 6 Saving Data in a Pd/oi OS Application 
by Danny Swarzman 






X 


reii'i 

*—<^>— 


o 

o 

jrwTi 



WD C 

D 








Links Among forms ... page 48 


A movie information drawer 


page 24 


Java Programming 

Dock Tile Imaging using JDirect 

S A pure Java approach to changing a Java application's 
dock tile at runtime 
By Andrew $. Downs 


Januawy 2003 • MacTkcii 


Table or CoN'rEKTS 


5 


































CETTIMC 

STARTED 


Copyright 2002 by Dave Mark 


A Taste of Project Builder 


As profTiised in Insi month’s column, this tnonLli weVt! 
going to take a walk iliRHigh the Project Builder dehugger 
Before we do, 1 want to touch on an issue that has been 
raised by a number of readers, especially folks who work in 
botli Code Warrior and Project Builder 

Where the Heck is the Siandakh Library? 

CtKleWarrior and Project Builder each have their own 
distinctive look and feel, especially when it comes to the 
Project Window. One point of confusion c'oncerns the 
location of tlie Standiird Ubmiy. In CodeWarrioc the Siandanl 
Library is (typically) explicitly Included in the project. 
Sometimes Uiis is done by cremating a project from a 
Melrowerks Standard Library (MSL) tem[>Iaie. Ollier limes, 
you adrl the MSL lil>rary to your project yotirself, choosing 
from a selection of precorupifed versions of the MSL, or 
perhaps custom compiling your own version. 

lioUoni line, when you look at your Project Window, 
you know youVe got MSL in your project because it is listed 
in the window along with all yemr otlier souixx* ccKle, 
libraries, etc. Want to get rid of the MSU Select it and hit the 
delete key. 

Project Builder follows a differenl tack. In the Proiect 
liuilder Project Window, there is no explicit reference to the 
Standard Library. The t|uestion people are asking is, ""Where 
the heck is it?" 

A member of Apple's Developer TckjLs leam kindly 
cleared away llte mist; 

With gcc on Mac OS X, the "standard C librar>^" 
(sometimes knowm as libc on Unix systems) is ]>ail of 
SystemTramework, wliich is implicitly brouglit in by 
gcc when linking. System.framework is a dynamic 
shared library, shared by all apps on the system, w hicli 
reduces overall system memory use. 

If the application uses C++, gcc alst) aulomatiailly 
brings in /usr/lih/Iibsrdc++.a, which is a static library. 

We currently recommend that developers avoid 
hiiikling frameworks (shared libraries) with C++ APIs, 
to avoid binary c'ompatibiliry' problems, Ix.x'ause gee's 


C++ ABI has iTeen in stjme flux. 

One other thing to note- for C & Objective-C 
APIs, we encourage the creation and use of 
frameworks. If .someone d(x^s want tt> build a static 
library and link it into their app, they currently need to 
follow the standard Unix naming convention of 
lil><foo>.a. See this Q&A for more info: 
http://developer.applexom/qa/qa200 1 /qa 11 0 1 .html 

Some of our conventions derive fn>m wanting to 
help enable easy porting of Unix programs to Mac OS 
X; we net^ to balance the u.se of Unix conventions 
ami Mac conventions, and try to make things seamless 
for everyone. 

Interesting stuff, If you launch Project Builder, then click 
on the Targets tab, you'll see a list of various settings, as well 
as a sequence of liuiU /%ases .steps. Tigure 1 shows the 
Frammmrks & Build Pliase. The point above was 

that the Standard Library wasn’t listed tn litis pane Ijecause it 
is built into Systemdramework and implicitly brought into the 
link prrxes.s, not as ati additional libraiy^ added to the project. 



Figure 1. Project lioikler's Targets fxtne. shotving no 
cuJtiiiiomii Fmniemtrk^i & Libraries. 


Does Pnjjeci Bulkier make use of makefiles? For you 
non-Unix folks, a makefile is a lexl Hie containing a script for 


Dave Mark Ls very tilcl. tie's lxx*n hanging around with Apple since before there was clearicity and has written a numlxr of IxKiks cm Macintosh 
development, including Hnim C cm the Macintosh. U*am C++ on the Maciniosh, and Hie Mactniosli Programming Primer series. Check out Dave's weh 
.site at hltj5://www.spidem^ojksxom 
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Asante Technologies -15 years of making Mac networking... 







Avuilahlc for 


n«iore<l l(X)-200 Mbps data 
transfer pipeline for each 
amnerted clkinL > 


Have an older Mac? 
See asantestore.com 


Asant^ continues to develop solutions that protect your data and your 
investment in networking equipment. Our new IntraCore 3500 series 
and FX4008 modular switches combine industrial strength with 
extreme flexibility.FriendlyNETVR2004 series routers provide secure, 
redundant communications links between corporate networks and 
remote offices - no special drivers or software required for Macs. 


Safer. 


Plug-and-play solutions like our new FriendlyNET Gini memory 
reader/writer make moving your data easier than ever* Set up 
the FR1004 series cable/DSL router in minutes and begin sharing 
the Internet immediately - with or without wires! 


Faster. 


Asant^ built the first Mac Ethernet adapter in 1987.Today we 
continue to speed up networks with the new FS41OOR series Fast 
Ethernet and GX5 series Gigabit Ethernet workgroup switches. 
Transfer digital content at blazing speeds over existing copper cables. 


"The reader to buy!" 

FriendlyNET Gini 
Memory Reader/Writer 


Ptjll sitfijnwl ftir Mur OS 9, 
X 10.2, 


Faster. Easier. Safer. 


for all of your 


WiFi, and ijihctmilb- 
iUMDinltik' fiLtwiirbi, 


O 2003 Asanud and PriendlyMET upgi-Jered tradcminks and AmLAN and Giro mv iwlenurkt ef AmxiI# TitrltrKtkigiM. 

AletlvrlrwlnTiarksafapiopeityOfOwtrtv^Wlllw inMVTS.AV rights rH«ved 


networking needs. 









building an application* Typic^tHy, ^ makefile will contain a 
*senes of build instructions, depending on the target l>eing 
built. Project Builder's Target pane is, in effect, a graphical 
makefile. More from the Developer Tools leant: 

Any other frameworks and lihnirles besides 
System.framework and libstdc++ will appear in the 
area you show in the st'reen shot. 'I he 'Sources’* Build 
Phase shows die compilation and link or<ler of project 
source files. 

No, there is no makefile under the interface 
that folks can look at* The internals of the liuild 
system are an implementation detail which w'c may 
change in tlic future* A developer can look at die 
detailed build log if iliey want to see the actual 
commands that get run during a build. To see the 
detailed build log, drag up die split bar at the iKiiiom 
of the build pane so tliat the summary is at the top 
and the detailed log is visil^ile below. 

To get a sense of tills, check out Figure 2. It shows the 
BuiUl w'indow' from the Hello, World projed with the spirt 
bars dragged wide open to reveal the Build spetifics. 
Personally, Td like to see this pn^ess opened up a bit more 
so t might tweak my compile/link insiniciions directly* 
Perhaps in a fuLure version of Project Builder* 


#J& O__ fmM: Hri m WgrW - Wwldt _^ 

\ i* ■«. 3 " ", •X.o.m.u m 


IIIf ■. .jMftnk* lAMfU- ACTIO H -h rf d _I»A 

MT_OCC.VR:SCIiiwi.i N^JOaiW.m* t Ltwuaii 11 

TwMiWih Au<u, iMMiiMiollHl&JiiiiW ‘ttCKim • ,iU«wMidaiwnnf%/thKUMnH 

vtaw- Tqpoai -iiU^mjfivwfPHlt/OkcHnMtii/ni^xvIa^MHTiKMNri^ mdi/hiMr TTMl 
OOT-/ilwn7rf»i«BW«/0*(k<n«f«wiH«*cfnj'ttM I wH OhHtt/tawM* TisnOOT- timfihttkt KioritlJM ‘ 

...upliftinf 


lp5wrc)w>Ji#l li iw H 
rcupipictt^isH m umiii 

HntirtbjDctfllijCHQlnB t/HotlistwWfllo fctldAulId/MtLa Mrtd.ouhti/Mtiha Mria.i 

b]*CUI->inrMtL/Prf>i«;UlUl htofltalnrOb I Ep.u 

flltl.^|KU.4lK|pdlW*Ht. 1^14^1 M/mikU MlM 
M14«1Mr1S 


iffRnpcTiitblltlli Mrlii 



Ikir I4MI l« If 

mt iMw i4^t i« u.hit urn I If nwrta jiunii^,kvic i 

bi.kfitf;^tfi 


Store it in die same directory as your other projects. 

The Foundation Tool project is hased on the 
PoLindaiion object framework and links In the Olijective- 
C library. Over time, well tackle the syntax of the 
Objective-C language and bcct>me familiar with the 
classes tliai make up the Foundation framework. For nt)w, 
let’s play with this project and see If we can't learn a l^ii 
about how the debugger wt)rks. 

In the project windows click on the Targets tab (the 
tabs are arranged vertically - sideways) and the Targets 
tab is fourth from the top* In the list that appears, click on 
the Heilobc target (you may need to click on the Targets 
disclosure triangle to reveal the llellobc target). In the 
new pane that is revealed, under Sellings, then under 
Simple View, click on the item GCC Ct)inpiier Settings 
(RemeinbcT last month's Terminal project? You compiled 
your source code with the command ‘"gcc*” GCC is die 
GNU C Campiler). 

Make sure that the “Generate debugging symbols” 
check box is checked* This tells project hLiiider ttj include 
debugging information when it et>mpiles your code, 
aiU>wang you to use the debugger to debug your program* 
Very Important! Take a look at Figure 3 to get a sense of 
what this looked like on tny machine* 


e©© _■ HHKi j r - Tpf M ifcamn __ 



Figure 2 , The Bttild //e//r>. World project. 

PiAY wriii Your Debugger 

As promised, Fd like to spend a bit of time going 
ihrtRigli Project BuildeFs deliuggcr interface. Ijninch 
Project Builder, then seleti New^ Project... from the File 
meiiiL Our last Prt}ject Builder effoii was a project of type 
“Standard Tool". 'I'his was equivalent to a Standard Library 
liased C console app. 'rhis month, well create a prt)ject of 
type "Foundation Tool”. Name the project Uellohjc and 


figure JL Akike sure the “Cenerate dehtigtiiug symbols'* 
checkbox is checked. 

liefore we try out the debugger, take the program for 
a spin* Click on the icon with the toobtip "Build and run 
active executable" (check out Figure 4). The Build 
window will appear and the program should compile and, 
finally, the Run window will appear showing t>ur classic 
"llellu, World!" output, much as it did in the C-based 
Hello, World project. 
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eoe 


■\ m i : [a] 

- ^ -UZM 


▼Targets 


■ Hcfii 

By^lcf and run active executable 2 ! 


-nw 


Figure 4 . Ciick on ihe third icon to huiki and rtm your 
project. 


Now dose ihtf Run and Build windows, leaving the 
Frojecr window open. Click on the File^5 tab, then select the 
file main an (yotfll find it under Source). As a reminder, 
Objective-C soiirce files end with the extension “an". Mere's 
the defatilt source ccxie from riiain.tn: 



ffimport <Foiindation/Koundii tlon - h> 


Int main (irtt arge* const char * ac&v[]) \ 

MSAiitoreleaseFool * pool ■= LtWSAutoreleasePoo] altorl 

ini L]; 

// injicft cock here... 

NSLQg(@*Hello, Worldr); 

Lpool release]; 
return 0 ; 

I 


Fetch 


let's replac'e the “insert code hei'e../” comment with a 
simple for kxjp we can follow in the tlebugger Here's tile 
new version of main an: 

^Import <FoundatIon/Foundation,h> 

int utriin tint, arge* conet char * argvlJ) I 

KSAutorRleaRePool * pool - [[NSAutoreleasePool alloc] 
init]; 

// AUdUl}; a kit ItMip fi)r debugging fun... 
int count: 

for t count’ll; count<-3; t:ouiit++ ) 

I 

NSLogC#“HeIlo, WDrldt“)j 

1 

[pool release]: 
return Ot 
i 

Note that we rephiced the NSLogC) call in the original 
code with u loop that calls Nblog 3 times. Run your new 
code. You should see the familiar console window, but 
this time with 3 lines of “Hello, World!" NSLogC) is a 
function you can use to gel output to the console window 
and ilic square brackets are mechanisms you use to send 
messages to objects designed to receive those messages. 
In the code above, we send an “alloc" message to the 
NSAuiorcleasePool object, then send the resuliing tjhjea 
an “init" message. When we are done, we send the object 
a “release” message. Nol to worry, well start digging info 
this syntax next month. 

For now, let's take this new code for a spin in the 
debugger. Close your Run and Build windows (not 


Best in show. 
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necessary, just doing this to avoid confusion). In your 
Projecl window, note the blank column just to ihc left of 
your *source code. This column holds your breakpoints and 
tell the debugger when to slop and wait for your input. 

Click just to the left of the for loop to crcale a 
breakpoint there. Figure 5 shows the breakpoint kx>n 
that appears. 


icon is one yt)u1l use a lot. Us toobiip says ‘'Step over 
method or function call.” Basically, it tells your program 
lo keep executing to the next line of code in ihe current 
source file. If the current line is a function call, it 
completely executes the function call, slopping before the 
next line of code after the function call. 


III 


ini Hin (int oonat dhor * ar9v[j) { 

« Tioot . 

// 4 CW fat d«txJ9Qiriq fw,». 

covfti 

for ( oojicUL; cDuntt+ ) 

^ IBljOQ<«'HeUo, wcriinOJ 
> 


[poDt t«le«e|; 

Figure 5* Click in the source code lo create a 
Breakpoint, 


Now lets run die debugger. Click on the 
hammer/spray can combo icon in the upper-left of the 
Project window. 'Ihe debugger window will appear 
(Figure 6), the program will start running, and die 
debugger will slop at our lireakpoini, immediately before 
exec'uitng the for loop. Notice the pink higlilighi bar that 
highlights the line of code chat is about lo get executed. 


e eo 


# K ^ L: 1 ^ *1 ► M » r? th 



Figure 6. The debugger^ stopped just before executing 
your for knip. 


Now step ilirough the execution of your program 
using the controls dial appear in the upper right corner of 
the debugger window. The triangle restarts execution 
from the beginning of your program. The second icon, 
pauses execution, just as if the program had hit a 
break point, 'fhe next icon resumes exeeuiion until the 
next breakpoint or until your program exits. The founh 


__ CD b , 

► II i» ^ (I) (t) 

; - ^ ^^Step over method or funa^ncall^ 

Figure 7 Click "'Step oi^er metbiyd or function calP* logo to 
the next tine of a>de. 

'Hie next icon adually steps into the function, stopping 
at the first line of ctxle within tlie function itself. The last icon 
rinishes execution of the current function, stopping ai the 
next line of code within the culling function. Add a function 
to the ctxle and give tliese conlrc^ls a try. 

As you might expect, the fields that show the variable 
values update as you step through the program. Notice that 
the variable count stares with a value of 0 and then 
intTements each lime through the imp. You can add 
breakpoints during execution by clicking next to a line of 
cfxle in the [breakpoint column. Want to get rid of a 
hreakixjinij^ Click and drag lo the left or right. Move a 
breakpoint by dragging up or down. 

To view your Stanclard Libnuy oiiiput, click on one of 
the two tabs towards die upper right corner of the debugger 
window. The Con.soie pane is a log of im|K)iiant debugger 
events inLerleaved wit!i your .standard i/o. ‘Hie Standard I/O 
windibw is puie, listing only the t/o itself, each tagged with a 
Lime-stamp and a code you can use lo link a statement to a 
specific execution of the program, liiich time ycbu restart your 
program, the code changes, and all i/o from that run will 
have the same code. 

Want to change a variable? Piece of cuke. Yi>u can 
double-click on a variable's value and, when the edit field 
appears, type in a new one. You cun also double click on a 
variable name and a new window will appear, letting you 
track that variable separately. Cool! 

Tiu, Next MoMni*.. 

Si>end some time playing with the debugger. Create 
some code (go buck to a Standard Library ick>I if you are 
uncomfortable mucking with Objective C), add some 
functions, |)luy, play, play. The delbugger is an incredibly 
important tool and you shotiki experiment with it until you 
feel comfortabie using it. 

Sec you next time! 


10 


GinriNC; Started 


MAc:fri':t:ii • January 2003 
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WIBU-KEY Software Protection 
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■ License Management 
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■ MacOS 9 &X 
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and heterogeneous networks. 
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SECTION 7 


By Rich Morin 

Still More Perl 


Munging Mail and Media... 


Peifs “whipitupitucle” is legendaiy. This coiLinin looks at a 
couple of smnil scripts IVe recently been "wliipping up’', 
showing how Perl can work in and around riioa^ fonnal OSX 
ttx)ls. One script, fmmf, I'inds Monster Mail Files; 1 use it to keep 
track of niailing list (and other) mail fdes which may Ixf gening 
out of liand. Tiie other stript, cfwc.d. is a daemon (harkground 
process) whicli helps me oix^raie an ex|xri[iiental webcam. 

Finding MOnstek MAn Fn.F.s 

Tm on quite a few mailing lists and I don't alw'ays get to the 
associated mailboxes regularly to keej) them under control I’m 
also trying lo irack the efficacy of my spam filtering .system 
(based on SpamAssiissin and End ora), wliicli drops suspected 
spam into one of several maill^oxes, depending on its numeric 
.spam rating, etc. 1 have written a short script which helps me 
keep on top of tlic'se issues. 

The mainline code, below, is quite simple. Using 
finddepth, from the File::Find module (available on the CPAN; 
cpan.perl.orgj, ii performs a dc^pth-firsl examination of my email 
folder. The callback function, wanted, is invoked for each 
ncKle (e.g., file, directory) in the tree. Using the lists produced 
by this traversal, the remaining code prints om the results for 
spam and miscellaneous email sorting each list in a case- 
insensitive manner 

?i'!/uiir/[>in/cnv iieii 
# 

^ (hiinf' (Ind nionsitr mail fiirs 
# Written hy Rich Morin, CFCI, 2lXC. 11 
use File 3rFiod: 

^monster = 2000000; 

I 

= ^/Usern/rdjn/Mail/Kudora Folder': 
f i nddRpth(\&wantRd , "$c«u/Hail Folder" J; 

for (son IlcCSa) emp ic($b)) (S^spaiti)) ( 


print Sline: 

1 

i 

llie tricky parts of this script, such as they are, lie in the 
‘wanted' callback Function. As it traverses the tree, finddepth 
changes the “current directory" and scLs Lcj tlie relative name 
of the iitKle. This makes it easy to skip over items that aren’t files 
and Hudonfs qable of contents” (*.toc) files. 

fiiib wanted I 

reiurn uriU^^s E T : 

return if ($_ ^ ni|\.toc$| 3 : 

For the next part, however, w^e need ilie "full pith name" of the 
ncxle. Gening this from a handy helper merhcxl, we on strip off rhe 
llrst t)art of the path and test the remainder in a.ssortcd ways. Perl’s 
(tegular expressions are very usehil tor this sort of name lauidling. 

$pflth “ SFiie::Find::name; 

$path B|*.*/EudDra Faldnr^Mail Folder^||: 

return if (Spath n!l_Tnact tve/ Savp/|); 

Afier picking up the size of (he file (in hyies), the script 
0 [xns eaeh maillx>x in the "s[>am" area and counts the nuitiber 
of “From: headers (i.e., messages). Fudora uses carriage returns 
(rather than the conventional BSD newlines) for line termination, 
but setting Perl’s $/ (input record .separaior) variable liandles that 
quire easily. The strings containing the formatted output are 
puslied ini<j a list, for use f)y the mainline code. 

= -a $„, 

if {$path mj ISpatnl) [ 

open(MB 0 X. $_] or die open mailbox($ ) ; 

$/ = Mr": 

Sfent = 0: 

while (dcfifte<i($Hri(? ^ <HB0X>JJ [ 

$fcnt++ if {$liiie =~ m|^FroEii:|J : 

t 

close[MBOXJ: 


print $line: pusli(@spatii, sprintf{“% B 5 s % 9 d 

I Spath, Sfent)); 

print "\n*: return: 

] 

for $line (sort 11 c($a) emp !c($b}) (®misc)) I 


Rich Morin has been using computers since 1970, Unix since 198.^, and Mac-based Unix since 1986 (wlien he helped Appie create A/UX 1.0). When 
he isn't writing this coluinn, Rich runs Prijne I'ime Frtx'ware (www.prfcoru), a pulilishcr of I’looks and CD-ROMs for llic Free and Open Source software 
comm unity. Feel (ree to write to Rich at rdfTli^pttcom. 
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THE BEST SELLING INTERNET COMPONENT 
SUITE FOR WINDOWS, JAVA, LINUX, 
SOLARIS, AND MORE... 


The cotic for niiscclhineoas inaillx)xes la a>tiiijara lively f>inipic. 
After ensuring that the mailbox is large enough to qualify as a 
“monster", it ftjrmals and saves the oiiiput lines. Peri's "x" operator 
comes in handy for creating a “quick and diny” histogram. 

return if (Seize < Smonster)i 

Sisiz “ int{$slze/$iionster): 
pushtftnlsc* sprintf 

$patb, Ssizo- *'* x SisizJJ: 


Tins sort of “personalized” s 
circles. Clearly, it isn't suitable fo 
short and simple enfmgh lliai it ca 
the needs of different users, 
my own systemr 

tSpaTu/?? Junk (ELidor^) 

ISpam/?? Junk (SA 1) 

ISpam/?? Junk (SA 2) 

ISpam/?7 Junk tSA 3} 

Lists/DocBook 

_Lists/frReBSI)/FreeBSD‘PortB 
_Listfl/FretiBSB/FreGBSD - Qupifi t 


cript is quite comtnon in BSD 
r use by others, as is, but it is 
n easily be customized to meet 
f is some sample output, frotn 


9041 b 

39192 6 

11467 2 

42053S 60 

3231686 • 

6431902 
2666962: * 


A WlbCam Dalmojn 

I recently .started playing with an iBO't', a I* ire Wire-based 
camera made l>y Orange Micro 

(www.orangemicro.com). My initial goal was to create a simple 
‘’security camer.r app that would display a set of recent images 
on a web pagt:. 

After downloiiding the OSX driver for the iBOT, I started 
looking around for image capture software. One package, 
EvoC^m (www.evological.com), captures images, ba.sed on elapsed 
time and/or software-lxised motion detection. It can also upload 
the image file.s (via l^fP) to a web serv^er and/or siive nuniliered 
copies on the kxal disk. 

IJiil'omiiiatcly, tliis wasn’t exiictly what I wanted. The FTP 
upload feature simply refreshed the .same file; turning this into a 
time history^ would Ix^ tricky. The numbered image files wouid 
do, however, if I could get tlieiii over to tlie web server. All told, 
it was a gcxid stan on w^hat 1 wanted. All 1 needed to do was 
eremite a little plumbing... 

The first [Xin of the yriumbing had to do with getting the 
files from my desktop Mac onto the (lYeeBSD-hased) local web 
.server. FreeBSD provides NFS, but getting OSX to mount the 
[)rovided volumes am be quite a trial. Fortunately, Marcel 
Bresink’s NFS Manager (www.bresink.de/osx/NFSManager.html) ease.s 
the pain considerably. 

Om:e 1 got tlie files sifting into a direciory on the wei> server, 
1 merely had to rename them (for convenience) and build up a 
web page to display a selected suliset, 'Ihe following scTipt, while 
still a “work in progres.s", accomplishes iliese La.sks quite liandily. 

»l/ii}ir/hin/env' pert 
* 

^ cfwc.d ■ Cjjnta Rm!a WdHjim Dai mun 
* Wriuen tjy Ridi Murin. Cl^CL 2(X)2.11 
SiingG «= ./iBOT^: f adjust to 
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- Follows Exact RFC Spedfi cations 
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- In Use By Almost All Fortune 500s 


- Royalty-Free Pricing 


IP*m>rks! for Mac OS X (10.0/10.1/10.2) gives you 
access to a host of new capahUities that will connect 
your applications to the Internet with unprecendent- 
ed easy of use, power, and flexibility! Your will he 
able to easily and quickly: 

- program the weh: HITP, WebForm, WehVpload 

- call web services: SOAP, XMLp 

- transfer files: FTP, TFTP 

- send email: SMTP, FileMailer, HTMLMailer 

- receive email: POP, IMAP 

- read/post news: NNTP 

- encode/decode: MIME, NefCode 

- access directories: LDAP 

- manage networks: SNMP. Whois, Ping, TraceUoute 

- build clients and servers: IP Port, IPDaemon 

- build packet applicat ions: UDPPort, Multicast 

- remote access: Telnet, Rexec, Rshell. RCP 


...and a whole lot more! - download your free trial 
today from www.nsoftware.com! 




software 

www.nsoftware.com 
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SbtBil “ * / .. i f adjust to taste*., 

t 


EOT 


for (::) | 

As mcnlioncd alx)vc, EvoCam g^^nemtes a unique niinie 
(e,g*, 123456789.ipgj For e;ich image file. In writing these fo the 
NFS-mounted FreeBSD machine, OSX also generates a 
companion file (e*g,, ,_123456789Jpg ) for the resource fork. The 
code Ixrlow creates a new name for the image file, based on the 
file's modifiaition time, and discards the companion file. 

# (Uon ouf incoming director)'. 

C3pendlr(IN, "$itagE/incojiiing''J 

or die "can’t open $iBigs/incoming"; 
iln = grept!/'^\ ./. readdir(IN)); 
chonpC^^in} i 
closed!r(TN )\ 

for $lti (sortCiln)} \ 

= stat(’’ $iiags/liicoia±ng/$iii'’); 

Sntliie * $stati9j: 

($acc, $mln, $hotir, $iiiday. $non, $year, 

$yday, $isdst) ^ localtiiDFL($intlEie); 


The code lx?low generates a 3x3 table of images, each 
followed by a centered lalxJ. I t on Id liave used llic file names 
(e.g., 2002.1129.2039jpg) as lalxis, hut that would have been a 
bit ugly. Wily not parse the names and reformat the values into 
a more readable format? 

Note tlie multi-line regular expression that is used to break 
up die file name. When REs get long and complex, lireaking 
them up in this manner can make them miu:h easier to follow. 

$cnt - 0: 

for ^i<9: ^i+“3) [ 

print OUT " <TR>\nV 

for ($1=0r Sj<3; Sj++) t 
print OUT " <TD>\n": 

$k = $i + $j^ 

$tmpl = $Ehow[$k]r 
$tinpl =~ 

ni|''(yt4l)\. 

f\d\d) i\i\6)\. #(MMXUm. 

t\dU) (\d\d)(Vd\d)\, ^UiJIXWMKJiS) 

$Liap2 = sprintfP'%s/%r./Xs at 

Si, S 3 . $ 3 , S 4 , S^j. $ 6 ): 


$0Ut - sprimfCXd.XQXdXQZd.WdltOadXOXd.jpe". 

SyeaH‘19D0, $rftcin+l, Smidayi Shour. Smin. Seek:) r 

renat^e (Sirngs/ incoming/ $iti". 

’’Simgs/i ,quetifi/Sout"); 
itnlink("$ljngE/inconu.ng/. $in") : 
t 

Perfs approacli to reading direekiries is rather messy, but it 
isn't all that difficult. Ihe code below gets a list of filenames, 
discarding any that don't match the desired format, and sorts 
them. Ik‘cause the names were crafted witli lliis in mind, tlie list 
is now in chronologit'al order 

»(ki Jbit of to display. 


print OUT " <CEtrrEK>\fi'* i 

print OUT " 

“<IHG SRC-\"iq/$tinpl\"><BB>\D-: 
print OUT " Stmp2\n“: 

print OUT " </CENTER)\n"; 

Scnt++: 


print OUT " </TD>\Er: 

1 

print OUT " </TR>\n^ 

I 


Finally, we push out tlie last of the 1 fTML, close the File and 
(Oh, yes!) move it into place for Apache to find, llien, after a 
second's repose, we go back up and do the whole exercise again* 


opfindfrdN, imgs/1.queue") 

or die "enn't. open $jrogf;/j. ^uouc": 

#ln ^ son Cgrep(/"\d [ 41A . \d (41 \ .\d 16 ) \ . jpgS/, 
readdir(IN))1; 

chomp C4iin); 
closedir(IN); 


Using Perfs "slice'' syntax, we gral> tlie last (i.e., most 
recent) nine file names, 

#show ^ tin I-9 .. -Ij; 


print OUT «EaT: 
</TABLE> 

</B 0 nY> 

<UTHL> 

mr 


close(OUT)r 

re name ("$htial/index, temp". 

"$html/index,htral”)j 
sleepd): 

t 

I 


Now we start genemting a web page The META tag tells the 
user's brow.ser to refresh the page every 15 seconds. 1 am nither 
comfiulsivc alxiui fonnatiing die HTML; the web browser d(je,sn’l 
care, but it sure makes debugging less painful for humans! 

» Make up ^ mrw web page. 

open (OUT, ">SHttsl /Index, temp") 
or die "caiiU open Index.iemp": 

print OUT «HOT: 

Onm) 

<HEAD> 

<META IiTTP-EQUIV“"Refresh- eentent="I5”> 

<TITLB>Ctnta Forda WebCais</TITLE) 

</HEAD> 

(BODY) 

<TABI.E> 


LtssoNS Learned 

As we all know, the Mac and BSD universes aren't a perfect 
fit. Perl is a very good *'g]ue language", liowever, allowing us to 
deal smcxidily with issues such as line tennination, extra (e g., 
resource fork) files, etc. 

Similarly, there are a wealth of u,seful ajips wliich can 
ix^rform suiail tasks, fill in gaps fietween ojierjting systems, and 
generally make our lives easier* If a $20 shareware package can 
.save me hours of fnistralion, the purchase decision is a no-bmtncr. 

UnluTtunaicly, some issues are siil! difficult to resolve. For 
instance, although it's easy to scin a Eudora mail file for header 
lines, editing Eudora mailboxes would lie far trickier. Aside from 
file locking prolilems, ilicre is the small issue of the (binary, 
undocumented) format of the TOC files. In short, choose your 
challenges airefully... 


14 


Snu. Mokk I’FRi. 


MacTfx^i • January 2003 









Abddirf 


HASP‘(Sf Privilege 


Don't let ''free roaming" software result In lost 
revenues — take advantage of the superior 
software licensing solutions offered by Aladdin 
Knowledge Systems. Did you know some businesses 
lose almost 50% of their revenue due to software piracy? 
That's why over 25,000 companies trust their software 


licensing to Aladdtn. Whether you prefer the proven 
reliability of HASP^ dongles {USB or parallel port) 
or the state-of-the‘-art downloading of Privilege^, 
Aladdin products have a 99.97% success rate. 

Call us at 1-800-562-2543 to prevent your profits 
from flying the coop. 


Aladdin 

SECUntNG THE GLOBAL VILLAGE 


e Aladdin.com 


















By Andrew S. Dowm 


Dock Tile Imaging using JDirect 


A pure Java approach to changing a 
Java application's dock tile at runtime 


Overview 

A previous article ("Dock Tile Iiiiaging'\ MacTech june 
2002) discussed using the java Native Interfiice technology to 
dynainiailly change the dock iiJe for a Java applicaiitsn. This 
article illustrates an alternate approach: tlie use of Apple’s jDirect 
teclinology to make the native API calls directly from Java 
wilhoul wriiing any C code. Tiiis elitninaies ilie need ffir a 
shared library and die scalTolding to call functions in ihal lil^raiyc 

The application discussed in this aiticle periodically 
fetches a new image from NASA's Kennedy Space Center video 
feed web page. The source page contains links to 15 channels 
(images). The application parses the source page to find the 
individual image links, then sequentially downloads each 
image. In addition to displaying each relrieved image, the 
application paints a countdown progress liar in the die 
between fetches. Phis progress bar painting uses the 
QuickDraw API, called via JOireci. 

APWICATION STARTIIP 

The JDireciDot:kTiler class conUiins mainO, the entry 
point for the Java applicatioiu niainO is used simjily to 
in.stantiate the DockTiler class ancl invoke an instance method, 
DockTiler creates an instance <jf IJrlDowmloader, which 
fetches an image from a URL. UiiDownloader invokes a 
method in Doc'kTiler, passing it the image bytes. 5ome of the 
code in thi.s class is reused from the June 2002 article, but is 
not discLKSsed again. Download the accom[)anying source files 
for this article, refer to ilie previous article, or send me email 
if you need more info. 

The import statements include two Macintosh Rum i me for 
Java (MRJ) package.^, one of which is JDirect. The otlier [lackage, 
macos.frameworks, contains declarations for the Carbon and 
ApplicationServices interfaces. 

import corn. apple. mrj . jdirect. ‘: 
import com .ijppl e. mr j , faucou. frumeworkH . * v 


public clasps JUirectDockTiler ( 

public static void main (String argE[J] t 
DockTiler dock = new DockTilerC); 
dock.run (): 

I 

] 

clasH DockTiler [ 

If we have trouble loading an image, the values of its width 
and height will remain -1. See loadlmageQ. 

Int mWidth = -1, mHeight = -1: 

The pixels are stored as a 1-dimensional array of integers. 
Three bytes of the im contain the RGB values, while the fourth 
byte contain.s the alpha (tran.sparency) value, 

Int mPixclsUi 

public DockTilerC) [ 

i 

Instantiate a class tliat handles periodic image leiching and 
display. 

public void riinf) [ 

Ortnuwnloiader u = now UrlDownlo^idert ibis D 
u .BetUi1( 

” http: / i spaceflight. nasa. gov / real data/ ksc 1 ive / index. htm I" 

): 

This substring will be lcK:aicd in the fetched page. This is a 
potential problem if the source page content changes, since ilien 
our substring search may stop working. This is a gotxl amdidate 
for a properly in an external file. 

u.setSearchString{ "http://scienue.kac.naaa,gov” ]: 

Tlic number tjf iteradons indicates how many Limes the 
substring occurs in the page, This is another potential trouble 
sp()t that could result in something breaking. 

u.sotlterationsf 15 ): 


Andrew lias iieen a Java Dn since lus llrsi encounter witii llie language at the WebHdgc HI conference in 1996. You can reach him at 
an £ I rew^d {>wns, Vi’s. 
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Fortuiiiituly, the Tlireuii sleep interv'al is entirely wiihin our 
control. J'he value 5{KX) shown here intliaiies the Thread should 
sleep for 5 seconds lx.'lwcen invcxialions. 

u.setSleep( SOOD ): 
y .istart () i 


static Frami^ f ” rtyll ^ 
static FictureFriime pf = null t 

'Hiis version of loadlmage() differs from the JNl versit)n in 
that it uses an array of bytes to create an imafte. Also, ihc 
grabPixelsO completion checking? is slightly im>re complicated in 
order to prevenl f>aniul or blank images from recurring. 

protected void loedlvaget bytie [] orriiy ) t 
Image Image 

Toolkit»getDefaiiltTooikit t) .createlmageC array 1; 

if { r r* null U pf I- null 1 
f.remove( pf 

if t f “ null ) 

f ^ new Frame( "image* ): 

// OrfN4:n^n wiixlows tnovc {>n.>crcim wliai yuit iiungr liir dock setUngs. 

// Kn'pjng it oasdtx'n pm m view ilic imglnul iiiutge well 
// ns the dock tile. 

f*setBoundst 50, 50* 200* 200 //omcrecn 

11 f.aetaouTids( 250, 250, 200, 200 J: //offscreen 

f,setLayout( new OaederLayoul[) ); 

pf = new PictureFrameC image 

r,add( "Center", pf ); 
pf,aetSi!£e( 128. 12S ); 

f ,packU \ 

t\setVi«ible( true ): 
f,repaintC): 

pf.repelnt 0; 

int width * image,goiWidihC pf ): 
int height = image.gellTcighr( pf ); 

if ( width < 0 II height < 0 ) 

return: 

mrixeln - new int( width * height \i 

for ( tnt i - 0; I C width ' heights i+i ) 
raPiitelai i 1 ' 0; 

PixelGrabber pg = new PixelCrafabert image, 0. 0. width, 
height. mPixsls. G, width ): 

try ( 

pg,grabPixelsO r 

while [ ( pg.gctStatiis{) * TniogeQbserver,AU3TTS } 
-0)1 

if { ( pg.getStatusO ti ImageOb server * ABORT J 
1 = 0 ) 
return: 

Thread,sleep{ 3000 ): 

I 

mWidth “ width* 
mhelght =* height; 

I 

catch C InterruptedException e ) I 
return: 


if C aiWidth > fl && mHelght > 0 ) 

Tniagent11s,setDockTile( tnPiKels. mWidth. mHeigbt )r 
I 
I 


Rftr]fmn(^ ma(;es 

There arc undt)ubtcdly tliird party, tjr perhaps Sun-provided, 
ebsses lliai can fetch and p;irse 1 flML pages, but the one discussed 
here amtuins the nec^siiry hmctionality for this app. 

The meihtxis in this class; 

- fetch a page at a given URL 

™ Icxate inaige links with a page 

- Fetch an image ai a ,spccii'ied URL 

public elasa UtlDuwnloader I 

The following atlributcs have c(Jm:spt>nding accessors (not 
shown); 

String mUrl * 
int mSleep = 0: 

String searchSlring ^ 
static int mCount = Or 

This corres|X>nds to the number of iteniiions. 

static Int max ^ 1; 

■Jills attribute is set from ihe consimctor, but ct>uld alst) be 
done wilh an acc:essor: 

DockTller 

UrlOownloader( OockTilcr dt ) I 
i i In-r di : 

1 

pubiic void start() 1 
dnwnloadPageO; 

Timer Is the actual thread, and is disais.sed further down. 

Timor t = new Timert this, mSleep ): 
t. run {); 

I 

This Inifrcr hokls the raw downloaded page content. 

StringBuffer sh “ new Stringlluf fer (J; 

This metliod uses a URL string to open a connection and 
download the content of tliat page, 

protected void download Paget) I 
try I 

URL url = new URLC mUtl ); 

URLConncctlon conn - utl,opetiComiecLion( J; 
int length ^ conn*RetContentLengtb(): 

BufferedlnputStreani is - 

new BufferedTnputStream{ url.openStreamO J; 
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int tqtal = 0: 
itit nutnRsad = 1; 


Return a 1-byte array in lieu of an em:ir code in case of failure. 


Rather than read the page as one huge chunk of data, read 
Ik pieces and append them to the buffer 


while { nuptRead > Q total < length ) { 
byte array[] = new byLel 1024 1: 
nntitRead = is. read( array ^ 0, 1024 3 ; 
total numRead: 

Sttlng s = new String( array ): 
sb.append( s ); 

I 

I 

catch [ KalfomiedURLExtovLioii g ) i 
System.out,println{ e 3^ 

catch ( lOException e 3 ( 

System.out.prlntln( e 


This method gels c:alled by the tijner Thread. It dispatches 
10 nieihods that locale the next occurrence of the search string 
00 the page, fetch the appropriate image, then call bac'k \o 
Dcx’kTiler to display tf> image. 

protected void fetch() [ 

Sf r ing 13 = parflcllrl [); 

byte array!] ^ fctcbTnage{ s 1: 

tiler.load Image( array }; 

I 

protected String parsetlrlO E 
String url = new StringO i 

Update the current image number. Reset after reaching the 
total numlx^r of image links on the page. 


mCount++: 

If ( fliCouiiL > m^x 3 
mCount = 1; 

int occurence = 0; 
int last = 0; 

String page - sb.toString()i 
Int index = 0, prevIndex " D: 

Hind the beginning of tiie next image link on llie ]>age. 

while t occurence < mCount ) I 

Index * page.indexOf( searchStrlng, prevlndex ): 

prnvTndcx - Index + 1: 

occuteiice++; 


Hind the end of the link: a quote efiaracien 

if ( index > 0 ) 

iirl “ page.substring! index, 

page,IndcxOr ( indcK f 1 3 3: 

return url; 


protected bytel] fetchlmageC String iniageUrl ) ] 


byte array!] “ new byte] 1 ]: 

if ( !imageUrl,startsWith( "http" 3 ) E 

System.out, println! '’Bad URL: " ^ image Url ); 
return array: 


try I 

fhis is similar to hew we fetched the page ccmtcnls alxjve, 
ext:epL that readFullyO eliiniiiates tlie loop. 

URL utl = new URLt iraageUrl ): 

URLConnection conn ^ url.openConnectionO; 

Int length = conn.getContentLength(); 

array = new bytel length ]: 

DatainpntStretim is = 

new DatarnputStream! url.openStream(} 3: 

int total = 0; 
int numRead ^ 1: 

is.readFully( array ): 

I 

catch ! MalfarntedURLExcepLion e ) [ 

System, out. println! "Bad URL: " + ImagcITrl ]; 
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array “ new byte[ 1 ]; 

1 

catch ( lOExceptlon e ) t 
Systera*out»println( e ); 

catch f IveAtraySisteExceplion e ) ( 

SyEten^oui^printlnC ‘'Bad array size: * + e ){ 
array = new byte[ 1 J; 


return array; 

1 

J 

This sioiplt' timer class rails the fetch() dispatch function, 
then sleeps for l/lOOth of the specified Thread sleep time. In 
between, it updates the progress bar at the bottom of the 
dock tile image. Upon reaching ID0% of the sleep interval, 
start another fetch cycle. To remove the progress bar 
updates, uncomment the specified Thread.sleep() call and 
remove the while 0 loop, 

class Tliaer jjipleiientR Hunnabt<» \ 
tfriDnwnloadcr nltrlPgunlender - null: 
int mSVeep " 5000: 

Tine rt Ur IDnvtiloader u, int sleep ) [ 
mUrlDownloader * u; 
fflSleep “ sleep: 

I 

pyblSc void ninU I 
while £ true ) I 
try i 

mUrlDownloader.fetch(): 

// Htrpbce ftjilowinf; witli thb line to avoid dnlwin|^ ol hiir. 

//Ttirod.sleepC mSIcep ); 

int total ” 0; 
lot i 0; 

float interviil ^ mSleep / lOD; 
while £ 1 <■* 100 ) I 

ImagGlItils.updateProgreRnSarf | inr )i h 
Thread,sleep( ( int )interval ): 
i + 4: 

I 

I 

catch t IiuerruptedException e ) I 

\ 

I 

} 


CALUING QlfARTZ 

The ImageUlil.s class provides java access to various 
native Mac OS API oils, such as the Quartz 2D (Core 
Graphics) library. The imports before die class dehnition 
include the JDirect package (containing the Linker clas,s that is 
used to register the native methods) and the 
ma cos. fra me works package (which defines the Carlx>n and 
ApplicarionServices interfaces): 

import coin. apple.mrj , jdirect.'; 
liipoTl com. apple »iBrj . macoa. framevorks. *; 

public class ItnageUtiis implements Carbon. 

AppIicationServlces I 


The linker constructt>r cal! registers the native meihtsJs 
declared in ihis class as |NI iTTetln>ds: 

private static final Object linkage “ 
new LinkerC tmageUtils.class ); 

TIte M;u' OS culls must lie declared explicitly. Aigument 
names are not irnporUim liere, I list'd letters as plac'eholders, but 
if you intend to reuse such a class it tiiay make sense to provide 
more descriptive names and possibly comments or 
dt>cumenLaLi{>n so you don't have to revisit the APt 
documentation each time, Tlicse tw^o Core Graphics dedaralions 
illustrate native methcxls without and with arguments: 

public iitatic n 0 ilve ini 

BeglnCGContextForApplicatloriDockTilel j : 

public static native int CGDataProviderCr©ateWitbData£ 
int a, int [] b. int c. int d h 

‘l*he non-native meiliod setDcK’kTile<) draws an image y.siiig 
the Core Giupliics API. Tlie arguments include an army of 
integers (^Tbytes) re]ire>stmiing ilie RGBA values for each pixel, 
and the intage wadth and lieighi. 

Etaiic protected void aetDockTilet int IJ iwagePixels. 
int width, int height ) I 

j'his value defines the number of liytes in eadi pixel: 

Inr kNuJnCortiponeiiLa = 4; 

'l ilts is somewhat annoying, having to redefine the constant 
values already defined by ihe API: 

final int kCCIiuagGAlpbarirst ^ 4; 
final int kCGRendGrlnglntentDcfault " 0: 

If you look at the API dues, you will iioljee that many of 
the values used or returned by the native calls are pointers. 
In [Direct (as in [ND, pointers map to the int data type, 'fins 
call gets the graphics context for the current application's 
dock file: 

inr thtCouteKt ” 

RegJ nCGCunlextrorApplicationDockTileO : 

If ( theContext != 0 ) I 

llie numlx'r of h\aes comprising one row of the image may 
be calculated using the numfx'r of pixels per row and the 
number of bytes fx'r pixel: 

int bytesPerRow ^ width * kNunCooipcinGnts: 

Create a data source using tlie [lixel array passed in as the 
image source, 'llien create an KGH color space obfeci. 

Int theProvlder ^ CGDaiaProvlderCreateWlthDalat 0» 
tningcPixels, ( bytesPerttow * height )* C ); 
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Ifjt theCol or space = CCColorSpaceCreateUeviceHGBO ; 

Now create the image* This is simiJar to creating a PixMap. 
The symlx)i kCGImageAlphaFirst specifies that in the pixel data, 
the alpha channel (iransparenty) value is in the first b)te of each 
int. More information can l>e fimnd ai: 
httpiy/developerapple.com/techpubs/macosx/CoreTechnologies/graphics/Qu 
artz2D/Quartz_2D_Ref/jndex.html. 

int thelmage - CGImageCreatet width, height, B. 32, 
bytesPerRow, theColorspace, 
kCGImageAlphaFlrat, theProvldet, 0, 0, 
kCGRenderinglntentDefault )t 

Cleiinup by explicitly releasing pointers to native objects. 
We could have left this until the end and cleaned up all 
resources at the same time. 

CGDaiaProviderK€leai>e( theProvidei: ): 

CCColorSpaceAeieaset theColorspace ): 

Use the newly createtl im;ige as the tile image: 

int theError = 

Sf^tApplleationDDckTileimaget thclta^ge }: 

Flush to ensure the pixels get written: 

CGContextFlushi theContext ): 


Finally* free the native image and the drawing context: 
CCImageRelease( theliaage ): 

EfidCGContextForAppllcationDockT!let theConLext ): 

1 

1 


Cajjjng QiickDraw 

'Phis portion of the InuigeUiils class is used to paint a 
progress bar over Ixittom of the image m tlie dock tile wliile ilie 
aj>plicuLi(m sleeps prior to fetching a new image. 

The QuickDraw 'J’oolhox declarations look the same as 
the Core Graphics method deciaraliuns just discussed. 
However, since QuickDniw uses non-opaque data structures 
in various ]>luces tliis set of declarations includes as 
arguments, for example, an array of shorts to represent a 
native Reel, 

public static native int 

BeglnQOConr ext ForApp1ica tlynDockTile(): 
public litarJc native Int GenPortBounds( int port, 
short I] rect ): 

public sciatic native void SetRect( short fl r, 

short left, short top, short right, short bottom ): 

Several color constants defined in the 1'ooilx>x must lx- 
defined here as well Ixfore they can he used: 

static final int blackColor = 33; 

static final int redColor = 205; 

static final int greenColot ^341: 


The progress bar is a 10-pixel tall redangle superimposed 
on the lower-edge of the dtxk tile. Ute Ixickground of the 
progress bar is red. with a black frame. Each update fills a laiger 
[XTcentage of the bar with green. 

static ptctficted void updateProgressBar( 
int currPercent ) t 

First obtain a rcTerence to the file drawing surface: 

int theFort - BcginQDContcxtForAppllcationDockTileC): 
if [ thePort != 0 ) I 

Next, create an bistance of a Rect class (discussed in the 
next section). Tfiai rectangle will hold the boundaries of the 
drawing surface. 

Rect theRect = new RectfJ; 

GetPortBounde( thePort, theRect.getArrayO }; 

The initial call simply frames the emfMy red rectangle: 

if ( cuErPerrent “0)1 

SetReett theRect.getArrayO, theRect,getLeft(), 
i short )( theRect.getBottom0 - ( shorr )10 ), 
theRect.getRigbt(), theRect.getBottom{j }; 
ForeColor( redColor j; 

PaintSecti tbeRecl,got Array() } ; 

ForeColorC blackColor ); 

FrameReetC theRect .getArrayC) J i 

The rigin edge of the bar inu.si be calculated using die 
curreni percent complete luuI the widtli of llie bar in f)ixeLs. The 
riglii edge is treatetl as a float Ixcause of the fractioas 
ciicoimtered during the calculafion, 

float right = 0: 

if ( currForcont >“ iOO ) 

right ( float ) theRect-getRight 0 : 
else 

right = ( { { float )theRect .getRigbt0 - 
( float )theRect,getLeft() ) / 

( float jlOO ) * ( float )currParrcnt; 

Fill the ''percent complete" area with green. Tlie right edge 
value calculated above gets cast to a short data type and used to 
define the rectangle to lx: painletl: 

ForeColor{ greenColor ); 

SetRect( theRset.getArray(). 

{ short )f thcRorr.g^rheft{} + t ), 

( fihori }{ thoReci, getHouomO 9 ), 

( short ) right, 

( short M theRect*getBottomO ' 1 ) ); 

PaintReetC theRect.getArray{) ); 


Flush the bits to the screen and cleanup; 

ODFlushPortBuffert thePort, 0 ); 
EudQOContextForAppiicationDockTiiil thePort ): 


I 
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Hvxy Suppt>RT CiAss 

jDirccl relics on various Toolbox structures that exist in 
native Mae OS libraries, hut need to be explicitly defined for use 
with JDirecr. Here ts one way lo define a class thai corresponds 
to tile Reel data strueturc: 

public class Rect \ 

private short [1 theRect “ new short! 1; 

The four comeis of tlie Reet are stored in an array whose 
sequence we af}:)itrarily ciefine as: 


theltect! 0 ] - Lefi 
theRoct[ 1 J = Top 
theRect[ 2 ] “ Right 
theRecti 3 ] = Bottom 


Tlie storage assignments are arbitrary because acce^ to the 
actual values is provided through accessor methods only, such as- 


public ehort getLeftO I 
return theRcct [ 0 ]; 

I 

public void getLeft^ &hort i ) I 
thoRectf 0 1 = 

I 


Altliough tile variations just discussed have rheir merits, the 
Rect iinpienientation for this project uses explicit get/set 
methods tor each corner of the Reel. The class definition is 
slightly longer, l)uL more forgiving, than an implementation 
requiring the caller to specify a numeric value for a corner as an 
additional argument to both gei/seu Also, this iitiplcmentation 
dtx-^s not expose ihe internal data repreamtation. 

References 

Tfje h(X)k Early Adopicr Mac OS X lava (Wrox Press, Inc., 
November 2001) contains an excellent chapter on integrating 
Java with native Mac OS calls using JDirect. TechNote 2002 
(http://developerapplexom/technote5/tn/ln2002,html) also discusses 
this issue. 

Thank you to Eric Albert, Greg Parker, and Nidiolas 
Riley for their assistance and advice while 1 wrote this 
program at MacHack. 


The constructor initializes the fields. The explicit casts to the 
slioit (i()-bit) data type convert each 0 value, which defaults to 
type ini (32-bit). 

public RecrO | 

sctTiCftf ( rshort JO ): 
selTopt ( short )0 ); 
setRightt ( short )0 ): 
setEottomC ( short )0 }: 


A more compact lliough iiTiplementaiion of tliis class could 
eliminate Uie accessor meth<xls and allow direct access to the 
data values, perhaps as four short values. Tliai exposure may 
lead to problems should you wish Ltj change the internal data 
representation. Always try to liide the internals of a class and 
enforce access through an Al^f. 

A more complex get/set combination that 1 1 ides the internal 
representation can lie implemented using constant values to 
represent each comer, as in: 


sLaLic final iiiL kLdt = 0, kTop " 1, kRlght = 2* 
kBottom - 3: 

public short get( short comer ) ( 

if ( corner >= kLeft && corner kRight ] 
return theRect[ corner ]; 
el ne 

// Not good because 0 bi a valid ^-alue for any t{>rner. 
return 0; 


public void set( short corner, short i ) I 
if ( corner >“ kLeft corner (= kRight ) 
theRect[ corner ] =1; 

// What if the caller pa^kse.s a had comer identifier? 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 


Animal Crackers 


Efthuticiug Cocoa QuickTiwC Applicatious tnovie in a window, and that this window provides a popoiit 

drawer listing some basic’ information about I he movie (Figure 1). 


Introduction 

In the previous QuickTime Tmlkit article ('"I he Cocoanuts" 
in Maclecb, Dcccinl^er 2002), we rook a look ai using Cocoa, 
Apple’s object-oriented applicarion framework, Lo develop 
Quicklime applications. We saw how to pul together a basic 
inu In- window ap plica lion thai can open, play, and edit 
QuickTime movies, and we also investigated a few ways to 
extend that application by subclassing Cocoa's buill-in 
QuickTime classes or by adding additional jnetbods to those 
classes with categories. 

In this article, 1 want to continue investigating Cocoa and 
Quick 11 me. Primarily, I want lo tie up a few loose ends that we 
didn E have time to address in the previous article, for instance, 
we need to dc) a litlle bit more work to gel all the iiems in llie 
Hdil and File menus working as expected, and we need to llx a 
few' minor cosmetic problems %vith the applicaiion. Consider this 
article then to be some fine luning to get our Cocoa application, 
MooVeez, to provide all the functionality of our sample 
applic ation QTShell, Along the way, however, I also want to take 
time to investigate a few' new k^pics, intrluding the wired aciion 
introduced in Quickl ime that allows us to set a movie’s scale. 
And, believe it or not, I m going to slip in a few tweaks to 
QTShell itself. Stj don’t be surprised if you see .some Carlson 
code along the w^ay. 

before we begin, 1 should note that in this article (and tlie 
previou.s one), we’re relying on the features of Quicklime and 
Cocoa that .shipfx^d with tlie .so-called Jaguar release: Ma<’ OS X 
version 10.2 or later, and Quicklime 6,0 or later. Earlier versions 
of the QuickTime Coc^oa classes, NSMovie and NSMovreView, 
have some noticeable |)robIems in a few key area.s. The Jaguar 
versions of these classes are much more reliable and efficient, so 
[halls what 1 11 a.ssLime we re working with. 


0 0 0 gi Sample M&vie 
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Figure 1: A movie htfonnalion drawer 


I’he ’ Source" is the full path of the Quick lime movie file. In the 
previems aiiicle, I offered the setSource: methtxl shown in 
Listing I. which breaks the pathname into its comi>onents, 
losses out the siring “Volumes", and then rebuilds a path using 
the colon (*’:") as I he path .separator. 


Usting 1: Displaying the movie’s source 

■ (void)setSource: (NSString •]riame 


sciikiurcr 


NSArray ‘p^tIiCDra|iorientf: = fname 

f:f)in|}onentESeparatedByStrlTil/”] : 

NSEnumcrator 'pathEnutnt^ralot ^ [paihComporiGiUis 
ebjeciEtimnei'iUor] : 

NSStrlng 'coniponsTit = [pathEniuiierater nextObjeetJ: 
NSMutableString ‘massagedPath = [NSMutabiaString string]; 


while (component nil.) \ 
if (((c:ontponent length] ) 0) 

(j^trcinp( [componeni cString] . "Volumes") 1"=^ 0)} i 
[massaged Pa til appends L ring: componj^nL] : 


DispiAYABf F Paths 

Ijci's lx.\gin with m easy liut impoitant ujxlate to our existing 
MtxiVcxi^z cckIc. Recall that our applic^ition cm open a Quickl ime 


coiQponeni = (pathlinnineratot nextOhject]: 
if (component !“ nil) 

[mass aged Path appendString:®" : ^'1; 

} else I 

component = [paihEnumcrator nextOhject]: 


Tim Monroe in a member of the QuickTime engineering team. You c’-an coniact him at monruc@applc,com. fhc views expressed here are not 
necessiirily shared f>y his employer. 
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LsourceNarae sctStringValuE; massagedPathl; 

I 

This isnl quite right, however, since il will uxss oiii a path 
t:omp<)nent narned ''Volumes** wherever it occurs in the full 
pathname (not ju.sl at the iTeginning), 

I have subsequently learned that there is a Cocoa method 
that can assist us here; the NSRleManager class provides the 
componentsToDisplayForPath: method, which returns an array 
containing the components of a file's di^playahle name (tliat is, 
the name that should be displayed to tlie user). So if, as atxjve, 
name is the full UNIX pathname of a file, we can gel the array 
of displayahle componems like iliis: 

fJSArray ‘pathCoinponents * [ iNSFileManager defaultManager] 
ComponentsToDisplayForPath: namel : 

For instance, the full UNIX pathname of the mtjvie file sliown in 

Figure 1 is: 

/Volumes/Medirations/Applications/QuickTime/Sample Movie 


Edit Menu 

'Ihere is one outright bug in the lagiiar iinplcmenLation of 
NSMovieView that rears its head when we try to undo a change 
to a movie. Do this: open a movie, select some of the movie data 
using the controller bar, and then cui die selected data. As 
expected, the Paste menu item is now- enabled; the prcsblem is 
that the Undo menu item is not enabled. (See Figure 2J We 
ought to be able to undo the cut, and NSMovieVlew should be 
handling this automatically for us, but it’s not. 



MooVeez 


Movie 


Window 


or.iJu 


Redo 


Cut 

sex 

Copy 

sec 

Paste 

aev 

Clear 


Select All 

SIA 

Select None 

m 


Help 


The ComponentsToDisplayForPath: methexi returns an array wiiose 
4 elements are these: 

Hediiaiions 
Applications 
QuickTime 
Sample Movie 

Hien we just neetl to reassemi>le these components with die 
ap]:>ropriate path separator. Listing 2 shows our revj.sed version 
of the setSource: method. 

listing 2: Displaying the movie’s source (revised) 

M.iSuurcc 

- (vold)setSnurcG: {NSSlring Unams^ 

I 

NSArray "'pathCamponents = UKSFil&Hanager defaultHanngfir] 
ComponentsToDisplayForPathinattiel: 

NSlsTiiamecator ‘pathEnumerator = [pathComponents 
objectEnumerator 1 : 

NSString “component = fpathEnumcrator nextObjectJ; 
NSHutableString 'dlsplayablePath = 
iNSMntableString string]: 

while (component f= nil) f 

if [[component length] > 0) I 

IdisplayabiePath appendString:component]; 

component ^ jpatbEtnimeratoT iiextObjocL] ; 
if (coEnponent 1= nil] 

IdisplayahlePath appendString:^";"J : 

\ 1 

component - [pathl^numerator nextObject] : 


LsourceName setStringVnl no e dIsplayableFath] : 

Ids perhaps worth mentioning that Girlxin applicadoas can 
call the Liuncli Services fund ions LSCopyDisplayNameForRef or 
LSCopyDisptayNameForURL to get displayahle path names. 


figure 2: the menu of MooVeez 

The Cocoa engineers are aware of this [>roblem, and 1 
lx.1ieve that a fix has been found and will lx* incor]x>rated into 
a future version of NSMovleView. In the meantime, there appears 
to be a fairly simple wtjrkaround t£) this problem. Tlie 
workaround involves subclaasing NSMovieView so lliat we can 
override the validateMenultfim: method, Listing 3 shows the 
override iiielliod. 

Listing 3: Fnabiing and disabling the Undo iiieiiii item 

valkUic.Mcnuitcm 

(WOOL] validateMenuItem: (NSMenuItEm *)item 

I 

BOOL isValid » NO; 

SEL action = [item action!: 

// handle the lJndi> menu iicm 
if (action — @seleoLor(undo;)1 I 

MovieConI roller rac = [self movicContrailcrJ; 

if [fflc) [ 

long flags ^ OL; 

MCGGtContrnIlerTnfo(mCt SrflagsJ; 
invalid = flags & mclnioUndoAvallable' 

I 

I eleo ( 

invalid = lauper vaiidateMonuitGai: itEm]; 


return isValld: 


Here we’re jusi calling MCGetControlleilnfD and checking the 
returned set ol' flags to see wfiedier die mdnfoUndoAvailaWe flag 
i.s set. If ir IS, we enable the Undo menu item; otherwise we 
disalile the menu item. Notice that we pass all other menu items 
TO the superclass (that is, to NSMovleView) 
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Once weVe added Uiis code to our subclass of 
NSMovieView, ihe Undo and Redo menu items are enabled and 
disal)lcd as expected, as shown in Figure 3^ In this case, the 
user has already cut st>me t>f the movie data and then undone 
the cut (that's why llie Redo menu item is enaliled). 


MooVeez 


File 


y Movie Window Help 


Undo 


Redo Cut 

osez 

Cut 

SIX 

Copy 

me 

Paste 

mw 

Clear 


Select All 

HA 

Select None 

m 


Fif^ure JL' 7he Htlit metm of MooVeez (revised^ 

In addition, tite Undcj and Redo menu items appear lo 
function correaly now. Take this new code for a spin: undo 
some cuts and pastes and see il’ everything works as expected. 
My preliminary tests do not reveal any problems, but Tm a bit 
worried by flie following con.sole message that appears tlic hrsi 
lime the user performs an undo operation: 

Warning; - [HSHovieVlew undo;! la nhflolr!te. 

1 recommend employing this workaround only after thoroughly 
testing it yourself. 


File Mewd 

Now that we ve got the Edit menu working pretty mucli 
as expected, let's lake a quick kwk hack at the File menu. In 
the previous anicle, we explicitly postponed adding supprm 
for creating new, empty movie window^s — that is, supporting 
ilie New menu item. To disable the New menu item, we 
added a validateMenultem: method lo our application 
controller class (defined in the file AppController,m). And we 
overrode ihe newDocumetit: method to act as a no-op. Since 
we want to add support for creating new^ empty movies, we 
need to remove these methods from our application 
conrroller class entirely. Once we do that, the delault 
IjehavioFS of die NSDocument rla.ss will kick in and we ll be 
able to create new empty dcKuments. 

For iliis to work correctly, how^ever, we need to make a 
few .simple fixes to the code that is called by the 
windoMCOritraile^^ mciliod. ffiilierto we have Lissumed 

that the user had opened a movie file by selecting llie Open or 
"Oj>en Recenr menu item and chcKising a movie file, or by 
dropping a movie file onto die application's icon. In eidier case, 
we know that the movie is associated with an existing movie 
file. Hut once we ailrm^ the u.ser to create a new movie, we have 
to make sure not io rely on NSDocument s fileName method 
returning a non-nil value. We'll revise tlie code in our 
initializeMcivieWindowFromRIe: methexi, as shown in Listing 4. 

Listing 4: Creatmg a new movie 

inilOii/i^MtJvit WEnii< wFn >m RIt* 

if ([seif fileNamel) I 

// open the nwivie file with featl^wriie fH^rmissicjn md loaci the movit- fnm H 
err " FSPatbMakeRef ([ [self flloHante] 

f llcSysLemRepreseiitatlon] , SifileKef. HULL); 
if (err = iJuErr) 
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err “ FSGetCatalogInfo{&tileRef. kFSCatinfoil one. NULL. 
miTX. ^fileSpec, HULL); 

if (err = noErr) 

err " [>penHovleFllc(&fIteSp^c. ^flleRefNiuii. 
feRdWtFcmi): 

if (err == tioErr) 

err - NevMovieFroniFile(&qtHovie. fileKefNuou 
&fileResNuin. miLL, 0. NULL); 

\ else f 

qlMovle * Ncw!1ovie(nevMovieActive) i 


As y[)u caa see, weVe cx>iiciitif>nalj5^eci the existing axle so ilmt it is 
called only if the dcKumenl already has a file asstKiated with it; 
otherwise, we siin]:)ly call NewMovie to cieate a new empty movie. 

We also need to make sure to set the wiixiow title to the 
last component of the file name only if die file actually lias a 
name: 


if ([self flleJiaiae]) 

I LwovleView window] setTitie;[self 
lastConponentOfFileNaiBel 1; 


If we do not explicitly set the window title, NSDocument will 
generate one automaliailly. Figure 4 siiows a new doc'iimem 
window wiili an empty movie. 


©00 Untitled 


I~ ► —--—- - - 41 ▼ 


f fgiire 4: A new. ewpiy diicunjeut window 


We can cut or copy data in other movie windows and then 
paste it into this new movie* And we can siive the new movie 
into a file, just as we would expect. 

Listing 4 is interesting also because it illiLstrales how to 
conven a string of t>^pe NSString into a file system siKxifiaition 
(of ty[ie PSSpec): get a C string representation of the NSString, 
create an FSRef, and then call FSGetCatalogInfo to get an FSSpec 
record from the* FSRef. Listing 5 shows this icciinit|ue [Xickaged 
into a nice utility method. 


Listing 5: Converting a pathname string inlo a file system 
specification_ 

NSSlrint'ToJ'SSpcc 

(void)NSStrlngToFSSpeci(NSString *)theFilePath 
fsSpoci(FSSpcc cbcFSSpecFtr 
t 

FSRef fsRef^ 

Boolean isDirectory ^ false; 

OSStatus err - noErr: 

// mm- an BRrf ftif the spedfietl tarpet fik 
tf (theFiUFath) * 

err “ FSPsthNakeRef([theFllePath 

f neSysieoiRepresentstlon]. &fsRef, &isDi rectory}; 

// create ;iii FSSpec record from the FSRef 


if (!err !isDirectory) ( 

err ^ FSGetCataloglEifo(&fsRef. kFSCaLlnroNone. NUTJ., 
NOLL* theFSSpeePtr. NULL): 

I 


This is useful because CoccKt likes to work with hill 
pathnames, while the Quicklime APIs tentl to prefer FSSpec 
records. Note, however, that the NSStringToFSSpec function 
works only whth pathnames that dcscrilK* existing files; if we 
pass in a path to a nonexistent file, FSPathMakeRef will return 
fnfErr (file not found) and fail to create an FSRef. 

[f we want to create an FSSpec record for a file that does 
not exist we need to be a bit more creative. Listing 6 defines 
the writeToFite: method, which might be ixdled (for instance) 
when the user .selects the '*Save As" menu item. As you can see, 
if FSPathMakeRef reiunis fnfErr, we call the standard UNIX file 
system functions open, write, and close to create a new file* Then 
we call FSPathMakeRef and FSGetCalalogInfo (as alKivc) to get 
an FSSpec record, whic h we puss to RattenMovie 


Listing 6: Writing a movie into a file 

writi!T.?Btc 

(BOOLjwriteToFilc:(NSString *)path 
ofType; (NSString ''Jtype 
t 

FSRef fsKef: 

FSSpec fsSpec: 

NSString "newPath: 

OSStacus err - noErr; 

newPath [NSString atringWithFormat pfichj; 

// tTfutf an FSRft fur ibc spt'citk'd Isr^X file 

err ” FSPnihKnkeRef ((newFrirh fi leSystemRepresentation]. 

ifsBef, NULL): 
if (err ^ fnfErr) t 

// tf tlic file dues mil ui ejsi.st,llien lei eremite I he tile 
int fd: 

fd “ npeji( [nevPatii fiieSystCfflRepreEentatlDnJ, 

O.CREAT I 0_RDWR. 0600): 

If (fd < 0) 
reLurn NO: 

write(fd, " * I): 

ciusG(fd): 

srr = FSPathMakeRef([newPath fileSystetuRepresenlationJ, 
&fsRef* NULL): 

] 

if (err = noBrr) I 

// ereuie an FSSpee reronl fnmi ihe FSRef 

err ^ FSGetCataloginfo{6faRef, kFSCnlrnfuNane, NULL* 

NULL, &fsSpec, NULL); 
if (err “ noErr) 1 
short resTd: 

// flatten the movie data into the specified yrget fde 
FlattenHoviet [ I_mtjvieVlow QTHoviel, 

flattenAddMaviuToOataFork 1 
f1attenFofceMovieResourceBef 0 toMoVteUata. 

&fs3pec * 

'TVOU'. 

smSysTemScript, 

createNuvleFtleDeleteCnfFile I 
c tea t eHuv i eFi 1e Do nt C r na t eRe b F 11e, 

&resld. 
nil): 
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le(refiTd): 

I 

rename([newPath fileSyateniRe^^refientation] , 
[path fileSystemRepresentation]): 
return YES: 

1 

// clean up 

uni 1 tilt [ [riGWPath flleSys LemRepresentatlon] ) ; 
rclurn MO: 


Window Resizing 

Id’s now lake a kxik ai a coupie of issues related to 
resizing our movie windows. Tyi>ically our doeiiment vvindow.s 
will be resized directly by the user, by dragging the resize I'Xix 
in the knver righi corner (if Ihe dtKiimenT window. In interlace 
ISuilden we’ve set die Size attril mies of the movie view as shown 
in Figure 5 

Q Q ___WSMflwgVtew) _ 

• Stoe ^ ^ 


mcActionController^eChanged movie controller action. So the 
first thing 1 want to do is rework our existing ctxle a bit, to factor 
out the code that sets the movie size. Usting 7 shows our new 
rnediod windowContefitSizeForMiivle:. 

Listing 7; Getting a window size from a movie size 

w i iklo w (Ain Lci iiSizcl t jrPidt j Vic 

- (NSSize)¥indowContentSizeForMovie‘ (Movie)qtHovie 
I 

NSSize size: 

Rect rset: 

GetMovIuBox( qlKovIg, &recL); 

si width - (flou t) (tec t, right - rect.lEft}: 

size.height “ (float)(rset.bottom - rect.top): 

// fnforte a minimum width (impurtuni lor stHinckmly movicji) 
if (size.vidth ^ 0) 

size.width (float)240; 

cOzc,width 2 • kHoviePuneOffseLI 
size.height +“ 2 ^ kHoviePaneOffset: 

if ([_EiiCivieView isControIierVisible]) 

size.height kMovleControllerBarHeight; 

return size: 

[ 


. Lock View ffiiniie 


r- iAVOut Rta 


iQPfUH ' iAndtnaieiiim ~ ^ 


i§ 


Y 


w. 2<C 
n ’ 


When ihe movie window is awaked from the nib hie, we 
set the movie window size like this: 

[[^EDvieView window] setContentSxze: 

[self windowContentSizeForMovie:qtHoviel]: 


Autdstxina 



jFfj^ wre 5: 7he size altrihules of the mome vkm} 

The avitosizing springs within the movie view and the rigid 
connections between the movie view and its superview (the 
dcK’ument w'indow) indicate that tiic movie view should grow or 
shrink to maintain a constant distance from all its edges to the 
edges of the documenr window. Ihat is, when the user resizes 
the document window, the movie view will automatically lx: 
resized to maintain its lx)rder. 

Occasionally, however, we need to adjust the size of the 
document window based on the desired size of the movie view. 
We did this previously when setting the size of llte window^ fear 
a newly-opened QuickTime movie. We’ll also want to adjust the 
size of the doeuiTient window when we receive the 
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And when we receive the mcAirtronContrdlerSEfiChan^ movie 
controller action, w^e can set the mt>vie window' size as shown 

in Lif^ting 8. 

Listing 8: Settin g a winiiow from a.movie size 

MyActicmFikcr 

case mcActionControllerSiiseCTiiangGdii 

[ [ [doc tnovieView] window] setConteniSi^e; 

[doc vindowContentSizeJorHovic: L [ [doc aio vie View] 
movie] QTMovle]]]^ 

break: 

Now^ when do we receive the 
mcActionC^nlroller^zeChanged action? Well receive it whenever 
the user manually resizes our document window, since 
NSMovieView informs the movie controller — probably by 
calling MCSetControllerBoundsRect — whenever the movie view^ 
is resized. (In this case, we really dotVt need to call 
setContentSize:, but it doesn't hurt to do so.) Well also receive 
the mcActkKiControllefSizeCh£»^ action when certain wired 
actions change the movie size. For instance. Quicklime 6 
introduced the kActionMovieSetScale aaion, wliich sets the target 
movie's scale {or magnificaiion). And earlier versions of 
QuickTime included the kActionTrackSetWlatrix wired action, 
w'hich sets a track's matrix. When the movie controller processes 
either of these actions, it will eventually inform our application 
of the size c:hange by sending the mcActionControllerSizeChanged 
action to our filter procedure. 


It turns out that tlie ccxle in listing 8 can lead to some 
drawing glitches when triggered by the.se wired actions. When a 
movie receives the kActionMovieSetScale action, our window can 
end up looking like the one in Figure 6. As you can see, the 
controller bar was not coneaiy erasetl at its previous position or 
redrawn fully In the new position. 

0 O @ ^ ^inSciiEeAciidn.itKiv 



figure 6: Dmiimg problems after a set scale aciion 

1 haven 1 investigated iliis behavior enough to know whether it's 
a [>rohlem in Qiiicklune's action-handling ct>de or in our own 
code. Bur there is at least one easy workaround: just inform die 
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movie controller that the movie has changetl, by calling 
MCMov^hanged. Listing 9 shows our upcUitcd code for 
handling the rrx^ActionControllefSizeC^^ action. 

Listing 9: Setting a window size from a movie size 
(revised) 

MyAciionJ'lltcr 

case tncActlQisControHerSiaeCbanged: 

[[[doc movifiVievl window] setContetitSize; 

[doc windowContcntSijieForHovie^ [ [ [doc movioVlev] 
movie] QTMQviclJ]: 

MCMovleChanged([ [due tnuvieView] niovlGCorilcqller]» 

[[[doc movieViewJ movie] CiTMovie]) j 

break: 

By I lie way^ tliis is not a Cocoa-specihc prohlem. It will also 
affect our Carbon-liast'd QTShell applicraiion. Accordingly, we 
sliould add a call to MCMovieChanged in QTSheil’s movie 
controller action filter pitKedure as w^ell, as shown in listing 10. 

Listing 10: Setting a window size from a movie size 
(QTSheU) 

QiApp, MCAcUonrUltTPnM; 

case meActiqnContrdllerSizeChai^ged: 

QTFraae _ Si e^W 1 ndowToMov i e (royW i ndowObj ec t): 
if tthf'MC CfjnyWintiqwOhjectl-fKuvie) 

MCHo V i 0 C h art gtd (LhyMC, {* “ myWindowOb j G'C t). tMovi e) ; 
laJlandled ” true: 
break: 

There is at least one other CKcasion when the movie 
controlU^r might .send us the mcActionContrallerSizeChanged 
aitiun, jiaioely when a streamed jiiovie clianges its size 
dynamically during playi:>ack. We don t need any addilit>nal eotle 
to handle this, bui we do need to teU tlie Movie 1’t>oll>t)x that we 
want to lie informed of any c*hanges in the size of streametl 
movies. We do this f>y selling a movie playback him when wc 
open the movie, as follows: 

SetMovi pplaytl i n tc:(qrHovic , hi nts Al I owOynamickcsl eg , 
hifTieAl lowDynpmicResizeJ: 

We are informed of movie size changes triggered by wiretl 
actions even if we doiTt set iliis play him, but not tht^se triggered 
by a dynamic size change of a streamed movie, 

ClJRSOtt ADJliS'lMliN’r 

As you know, some media types change the cursor image 
as it moves over various regions in a track. Flash tmeks and 
wired sprite tracks often do this, and QuickTime VK d<x.‘s this as 
a matter of course. (And with a vengeance: QuickTime VR 
defines nearly 80 different cursors that can 1^ displayed as the 
user jK^rfonns oj>eniiions within a panoramic movie, and over 
too watiiin an object movie,) Figure 7 shows a QuickTime VK 
movie with the mouse lying on top of a link hot spot (that is, a 
hot s(K)l lliat, when clicked, moves the user to a new node). 


0 Q 0 _ ^ campus,mov 



■~i__ ~ ~v - -T""— 

figure 7: A QuickTime VR node with (be mouse over a 
link but spot 

The trouble is tluit some media Ly|x:s don't change the 
cursor back to the default arrow' airstjr when it moves outside 
of the movie box, Ihe result is that our application ends up 
disfdaying an incorrcci cursor, as shown in Figure 8. The mouse 
is just to the right of the movie Ixjx (toward tlie top of the 
movie). Note that its image is still one suj>plied by QuickTime 
VH. not ihe siandard arrow cursor. We should fix ihau 

ee© 5 campus.mov 


0 





Figure 8: A QuickTmw VR cursor di^)ktyed mitside the nuyvie hooc 

Adjusting the Cursor in Carbon 

Before we see how to adjust the cursi>r in our Cocoa 
appUcatiori, let's digress briefly to ctmsider how we already do 
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this in our Carbon application QTShelJ. listing 11 shows the 
dcRniiion of ihc QTAppJdle function, which we call whenever 
we receive un idle event. As you can see, we simply check 
whether the current mouse position (w^hich wc gel by calling 
GetMouse) is outside of the front movie window or front 
movie winclow‘s visil>le region; if the mouse is indeed outside 
of these regions, we call MacSetCursor to reset the cursor to 
the arrow cursor* 


listing 11: Adfustiug the curs or in an i dle procctluiH! 

QTAppJdle 

void QTApp_Idle CWlndowReference theWinfiav) 

[ 

WiftdowOfejAct tnyWI ndowObject = NULL: 

RrflfPtr fiySav^dPact: 

GcMPort £ 6mySavedPort): 

HacSet Port (QTFrame^CetPo rtFrotnWlnd ovRef e rence (theWi nd ow) J r 

myVindowObject “ QTFtame GatWindowObjcctFroniWlndaw 
(theWindow): 

if tmyWindowObjoct NULL) ( 

Novi oCojni roll ar myNC = NULL: 

nyMC * (*"myWindowObject).fController: 
if {nyMC r= NULL) I 
TARCET_0S. KAC 

// rt'siott ttic curMtr tu lire amtw 

// if it's outsklo tht? iVtMii nxivk wiraluw or the wiiKlow s visiiijc rcgioii 

if (tbeWindow = QTFriime_GetfrQtitMovieWiTidov()) \ 

Rect aiyRect: 

Point myFoint: 

HgnHandie inyVisReKlon: 

Cursor myArrow; 

GetMoune(^myPolnt]; 
myVifiRoglon NcwRgn(h 
Got Port VisibloRfsgioti 

£ QT F r t P o rt P r oaiWi nd owHe fe tanee (t h aW i n d ow), 

myVisRegion}: 

CetWindowPortBouDdsttheWindow* iiiyRect): 
if UHacPtlnRect(myPolnt* iuTyRert) |j 
! Pt I nRgn (my Po i ni. my Vi sRt^gion)) 
MacSptCiirfiQr(GetQnG1obalsArrow£&niyArrow)): 

DisposoRgalmyVisKegioiO : 


ilPendif 

) 

J 

HacSetFortCraySavadPort): 

1 

Frankly, this Is old-style Mac programming. It works well 
enough, hut its likely to eat up CPU cycles unnecessarily since 
it’s still stuck in that old f>tjl]ing mindset. Let’s upgrade Ql'Shell 
by reiniplementing cursor adjusting using CarlxHi events. (For a 
general discussion of Carbon events anti QuickTime, see ""Fvent 
Horipam"' in MacTccb, May 2002.) 

My first attempt to use Carlxm events heie was to have the 
window event handler register for events of cla.ss 
kEventClassMouse and type kEventMouseMoved After aU, we 
need to check to see if die cursor needs to change only if iCs 
Ixeen moved. The trouble is tliat a movie in QT’Shell completely 
fills the conieni region of a movie window^ (except for die space 
txx'upted by die controller bar at the fxiiitmi of a movie window)* 
Once the cursor moves out of the movie tt) the left or right, its 
uu k>ngcr over the movie window and lienee subsequent mouse 
movements will not trigger kEvenlMouseMoved events Ibr that 
movie window. 

So I ended by having the application event handler register 
for kEventMouseWloved events, iis shown in Usting 12. When it 
receives a mouse-moved event, ii retrieves the position of the 
mouse and ilien checks Xn see if the mouse is cunently outside 
die frontinosl movie window, If it is, the cursor is reset to die 
defatiii arrow culsol 

listing 12: Adjusting the cursor in a Carhort event handler 

QJT’rjinK'^Cartii JiitvcnL^jspi iamtlcT 

Crtsti tcEwentClasijHfjuse: 

switch (myKind) f 

case kEvetitHous^McivecI: 
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Long Distance 


myErr = GetEvcntraranjcter (iheEvent, 

kEventParamMouseLgcalion. typaQDPoitit, NULL, 
g t steo f (Poin t). NULL * P oint): 

if (aiyErr = noErr) \ 

WindowRef ByWindov ^ NULL; 

Keci: inyRect: 

Cursor myArrow; 

GlDbalToLDcal{&nyPolnt): 

// get the ftoni mrnif i^indow 

myWindow ^ QTFramo^GetProtitMovieWindowt): 

if (mytfindow !“ NULL) I 

GetWindovPortBounds(KiyWindow* ^myRect): 
if ti PtInRect CtnyPoinr. imyRect)) 

MacSatCtirsor (GatODGlobalsArrow(^!iyArrow)); 


bcGak; 

I 

break; 


Tins strategy iipptrjrs lo work quite nicely, and it avoids the 
polling l^ehavior of our original code. Strictly spc^aking, we need 
to adjust die cursor only when a movie contains inlenictive 
tracks (tiiai is. Plash, wired sprite, wired text, or QuickTime W), 
since they are the only kinds of tracks that are likely to change 
the cursor from the default arrosv cursor. I doubt, Ijowever, that 
there is muclt to 1^ gained by checking for interactive track 
lyyK-.s liere. It s prohahiy Ixtter just to reset the cursor to the 
arrow for every kind of QuickTime movie, as we do here. 
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Adjusting the Cursnr in Cocoa 

Let's return lo the more pressing concern of adjusting die 
cursor in our Cocoa application. There are two (principal ways we 
ran return the cursor to its default arrow shajie when it moves 
uutside of ilie movie retnangle. First, we can add a tracking 
rectangle to the NSMovieView view that lioliLs our mttvie, by 
exeaiting die addTrackingRect: metln)d. For iastance. inside of 
wiiidowCoatrdlerOidLoadNto:, we am execute this line of ccxle: 

IjiovieView addTrackingRect; Ltfit^vtcVici^ bounds] owtiotiself 
iiserDatainil assiimoTnslde;NO] ; 

The addlrackingRect: meihtKl causes ihe spr^iRed owner to 
receive mouseEntered: and mouseExited: messages whenever die 
riKHist' is moved inro anti out of the spt^'ified rectangle inside 
tile target view. The message axipieni is often the same view 
whose rectangle will lx* Iracked, bui it need not be. In the 
present c:ase, indeed, we are st^tting the tlcKiiinent instance as 
the owner, so that these messages are sent to it and not to the 
movie view. This allows us to define mouseEntered: and 
nxHiseExited: within our custom document class, so that we do 
not need kj subclass NSMovieView. 

Actually, since we are only interested in knowing wiien the 
mouse leaves the movie view, we shall implement only the 
mouseExhad; method (Limiting 1J), 

lasting 13 : Handling mouse-exited messages 

' (void) motiseExlted; CNSIvent*) event 

I 

// sti cursor to the deiiiiih t!ur?iOT 


1 VWW. laurcosfcfr alf ftgf. com 
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t[NSCursor fltrowCursor] »(k]; 

J 

Here we send the factory iiiethod arrowCursor to the NSCursor 
class and then set the resulting cursor. 

It lurnnS mi\ that windowContfollerDidLoadNib: is not really the 
best place to call addTrackingRect:. The main reason for tills Is tkit 
the tracking reaangle is not autoniatiatlly re-sized when the target 
view is resized Rather^ we need tt> explicitly remove any current 
tracking rectangle and then add a new one each time tlie movie 
view changes size. So let’s miike tlie call to adcffracking Reel: insicie 
of our movie controller action filter pr(X’edurt% when we handle 
the mcActlonControllerSizeChanged action, lisdiig 14 sliows our 
revised ctxle for handling this action. 


listlQg 14: Resetting the tracking rectangle 

MyAttionFilicf 

case racAcLioiiCotilroll^ji:SizeCliaiiged: 

[[[doc QiuvleView] window] setCoivieniSl^e: 

1doc windowContenxSijeforUovie: 

Ittdoc movieVlewl aovie] QTHovieJlj: 
ffdoc movleVlGwl reaoveTrackiiiRltect: 

fdoc trackingRectTagll: 

[doc setTriiCktngRcctTag: f [doc iiovieVlewl 

addTrackingRect; [ [doc roovIfiVlew] hounds! owtiettdoc 
U3er0aia:riil ussum.'inside:NO] J: 

MCHejvieChaiiged( t [doc wovieView] aovieControllor] . 

[[[doc isovieVlewJ aoviej QTHovieJ): 

break: 


Fil'st, we send the removeTrackingRact: message to the movie 
view to remove any existing tracking rectangle. Notice I hat 
removeTrackifigRect: takes a pararneten which stx;cifics a trackiim 
rectangle (of the scalar type NSTrackingReetTag). 'Ihis tag is 
returned to us by addlrackingRect:. and w'e are storing it in the 
new instance variable _trackingRectTag in our document class. 
Since we are calling removeTrackingRect: and addlrackingBect: 
within our movie controller atlion filter procedure, the dfx’ument 
cliLss needs to pnwide accx^ssor rnethixls for us to get and set the 
lag. listings 15 and 16 sht>w our delinitions of these two 
methods. Nothing eartlishaking here. 

Listing 15: Getting the tracking rectangle tag 

inickiniiKtcakg 

(NSTracki ngR^tTiig) t rack i jagR(>ctTa g 

{ 

return _LriickingRectTa^: 

I 


Listing 16; Setting the tracking rectangle lag _ 

jiclTrack inpRcctTas 

(void)setTrackingUectTag: {NSTrackingReetTag! rectTag 

I 

_tracklngRectTag ^ rectTag; 

1 

'Ihe second way of adjusting our cursor is to define a 
cuntor reclangle for the movie view. A cursor rceiangle is a 
special kind of tracking rectangle. What’s special about it is 
that NSView knows that the rectangle is likely to change if the 
associated view is resized or moved. Accordingly, NSView 
calls the view’s resetCursorRects method whenever that 
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iKtppuns, U> give Lhe view a ch^nee U) resize or move the 
cursor rectangle. listmg 17 shows how we might define tfie 

resetCursorRects method. 

listmg 17: Resettibog flie cursor re 

rtr.stK^iirfHsrRtcLs 

- (void)rfififitCursorRccts 

NSCurEior ’newCuffior: 

[super resetCursorRectsj; 

newCursor = [NSCurBor arrowCursorJ: 

[self addCuraorRect:[self bounds] cursor:newCursorl; 
[newCursor setOnMouseExltediYBS]; 

J 

Here we create a new anow cursor anrl call addCursorRect: to 
attacli it to a new cursor rectangle that is as large as ilie target 
view^ (that is, the movie view). Uhen w^e call setOnMouseExited: 
to configure the curst>r to set itsefi’ as the current cursor when 
the mouse moves outside of the cursor rectangle. 

As you can see, there is much less code required when 
using cursor rectangles tlian w^hen using tracking rectangles. We 
don’t neec.! to keep track of llte tracking rectangle lag, and we 
don’t need any accessor functions to pass that tag to the intw-ie 
controller action filler prcKeclure. 'Hie only downside to using 


cursor reaangles ts that we must subclass NSMovieView (so that 
wc have a class to define ilie iBsetCursorRects method). As we 
saw above, we did not need to suixdass NSMovieView when 
using tracking rectangles. 

Conclusion 

111 this anicle, we revisited the basic Cocoa movie playing 
and editing application that we developed in the previous 
article, witfi an ewe to tying u[> a few' loose ends. We ve now got 
all the items in the File and Edit menus w^orking as expected^ 
and weVe cleaned up a few cosmetic glitches in our original 
version of MooVeez. Witli iliesc iirif^rovements, M(X)Veez now 
matches quite closely the capabilities of QTShell, our l^enchmark 
Carlion movie playlxjck and editing application. Moreover, the 
Cocoa Ira me work u|K)n whicli MooVc-ez is fiuilt [>rovides a 
number of additional features not found in (;^T.Shell, including 
the "'Open Recent” menu item in the File menu and the Window 
menu for managing all open document windows. 

Crldiis 

listing 6 is based on some code by Vince DeMarco. 
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MAC OS X 


By Rich Morin 


CamelBones 


Creating GUI-based apps with Perl 


Sherm Pendley bills CamelBones as Objective-C/Perl 
bridge bajnemfork". The web page goes on to say 
XameiBoncs is a IrafTiework lhai allows many types of 
Cocoa programs to be written entirely in Perl. Ii 2 ilso provides 
a high-level object-oriented %vrapper around an embedded 
Perl interpreieg so ihai C<Koa programs wriiien in Objective- 
C can easily make use of code and libraries wriuen in Perl/’ 
jumping from the general to the pailicular, CamelBones 
allows a Perl scripter to create GUI-based apps, with only a 
modicuni of pain (read, ObjecLive-C Because the scripter 
can use Interface Builder, the graphic layout is painless, 
cjuick, and likely to yield attractive results, 

Limiiations 

Sheriii says that Came!Bone's biggest ciirfem limitation is 
inheritance. Ii\s no\ yet po.s.sibIe to create a Perl sub-class that 
inherits from an Oi>jective-C sub-class. As a result, 
CamelBones can t be used for: 

• Document-based applications, which rcc|uire a siibclass of 

NS Document. 

• Cusloni controls and/or cells, which require a subclas.s of 

one of the many NSConirol or NSCell de.scendants, 
respectively. 

This limitation will be addressed in the next version 
(0.3), which Slierin expects to have ready by die time this 
article is in prim. Meanwhile, most of the tasks which could 
be perfiormed !>y a cub-class can lie handled by a Delegation 
or Notification callback. 

Camel lk>nes has some other prol^flems, at least from my 
perspective. Because ilte app needs to be ‘"built” (with 
Project Builder) rather than simply run, tlie build time 
becomes a noticeable pan of the edit/test cycle, I think that’s 
just the price we pay hir using compilers and linkers 

Also, most of the existing Cocoa documentation as.sumes 
that yoirre using Ohjective-C, This means that you have io 


have a reading knowledge of OI>jeeLive-C, as well as tlie 
ability to turn method prototypes and example code into their 
Perl equivalents, i find this livable, however, and help is on 
tlie way for both problems 

Getting Started 

Assuming that you already have CSX and Apple’s 
Developer Tools installed, adding CamelB(jnes is cjuiie 
simple, Go to bttp//camelbones.sf;net, download the 
distribution, and install it! At this writing, the documentation 
is still a bit sketchy, but the author plams to iiTit)rovc it Real 
Soon Now, so it may be in significantly better shape by the 
time you see it. 

The package uses a standard installer, so installation is (giiie 
easy. I'd suggest that you choose the “Custom” install, so that 
you can get the source code (why not?). 1 haven't looked at 
tlie code. l>tit T assume that it’s a combination of Objective-C 
and Perl. Nice to have around, if you get frustrated l)y some 
peculiarity or simply become curious about how it all works. 

If you are thinking about using CamelBones in a proprietary 
offering, you may want to lt)ok over the license a bit. 
CkimelBones is released under the GNlf Prc^ject’s "Lesser General 
Public License” (LGPL)^ Bnefly, the LGPL allows your app to use 
(CamelBones without any requirement ihat the author provide the 
source code for the application (though w'iih Perl, source 
distrilxition is the default ca.se). On the other hand, any changes 
yt>u make to CamelBones ii.seif mu.st be made available to 
anyone who gets tlie “binaries”. 

Once yoti have CamelBones installed, i strongly sugge.st 
that you skim the documentatif)n and walk through the 
HowTo examples. As a newxomer to Interface Builder and 
Project Builder, this taught me a bit about the capabilities and 
operatif3n (jf eath. Pven if you are expert at IB and PB, the 
examples will give you an idea t>f what kind of Perl code 
CamelBones expects. 

In brief, however, Perl code for use with CamelBones 
looks pretty much like Perl code to work with any object- 
oriented API. Stuff like: 

sub sayHello [ 

my ($eelf. Seender) ^ 


Rich Morin has been using compuicr.s since 1970, Unix since 19H3, and Mac-hiised Unix .since 19R6 (when lie helped Apple create A/UX 1.0), Wlien 
he isn't writing this cokimn, Rich runs Prime Time Freeware (wvtT^'.ptf com), a jiulilisher of hooks and CD-ROMs for the Free anti Open StHjrce software 
community. Feel free to write to Rich at rtlrn^faf.coin. 
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^TextLabel' [ - >BetStriri^ValueHello"■} : 

NSLoa("Hello, world 

] 

One peculiarity, discussed in the OimelHones weh 
pages, is ihaL Camel Bones doesn 't (yet ) provide "toll-free’' 
bridging of Perl hashes and lists to Cocoa’s collection classes. 
Consequently, the Peri code has to deal witli the Cocoa 
collections explicilly; Instead of writing: 

tny 

my ^key = 'abc': 

$haBhl$key1 = ^def': 
prinif ("key^liE , value^%s\n'*. 

Skey, SbashI$keyI): 

you have to write something like: 

my $hasb = NSMiitableDictionary >b11oii 
my $key = 'abc'; 

$h3sh ->set0b ject_fcjrKey ($key, ' def'); 
prirstf ("key^is, value=ls\n” , 

Skey, $ha 3 b->objectForKey(Skey)); 

Also, because Objective-C rloesn't provide automatic 
tPerl-sLyle) garbage collection, you may need to exi)licilly 
reserve and release any Objective-C objects which you 
create. Ihis looks pretty tedious, to my Perl-accustomed 
eyes, but I m consoled by the facts iliai (a) I only have to use 
Cocoa collections to access Coco a-specific items and (b) 
relief is said to he on the way. 

Packaging Issues 

Ease of distribution and insiaUation has iK^en a 
CamelRones priority from the start. All that the end user 
needs is a copy of Came [Bones, framework. By default, 
applications look for this in /Library/Frameworks, so the 
easiest thing to do is to create an installer package that will 
make sure that the franiework can be found there. 

But, if a developer wants a drag-and-drop install and is 
willing to rebuild the framework with the appropriate Project 
liuilder options, the framework can be embedded in the 
application bundle itself. CPAN (Coiiipreliensivc Perl Archive 
Netwfjrk) moritiles can also be included in the application 
bundle, eliminating another common .source of pain for end 
users of Perl programs. 

Version Creep 

The CanielBones fiamework is linked against the Perl 
interpreter (Version 5.6.0) that is shipped with USX. Sherm 
has gotten reports that Perl 5.6.1 works fine, as long as ids 
compiled and installed identically to the original 5.6.0, but 
5.8.0 definitely doesn’t. So, if you have added Perl 5.8.0 to 
your system, you may have to rebuild any CamelBones app.s 
you receive. 

As time goes on, Apple is quite likely to release Perl 
5.8.0 (or whatever) as an update to OSX, Unless a 
workaround is found, this will cause all 5.6.0-based 


CamelBones apps to break. Fortunately, some Very Bright 
People are looking into the matter, so a fix is likely. 

Resources 

Perl wizard Dan 8ugalski i.s currently writing 
' Programming Cocoa Applications with PerP for O'Reilly, but 
a publication date has not yet been estalilished. The book 
will cover CamelBones in depth, however, so watch for it! In 
the meanwhile, Dan promises to put up some example code 
on the CamelBones web site. 

Notwithstanding tha fact that they assume Objective-C 
usage, most batiks on Cwoa, IB, and PB are relevant to 
CamelBones Here are .some you mighi want to look over: 

^Building Cocoa Applications; A Step-by-Step Guide” 

Garfinkel and Mahoney 
O’Reilly and A.ssociatcs, 2002 
ISBN 0-5%-00235-l 

“Cocoa Cookbook for Mac OS X” 

Bill Cheeseman 
Peachpit, 2UU2 
ISBN 0-201-87801-1 

“Cocoa Programming for Mac OS X” 

Aaron Hillegass 
Addison-Wesley, 2001 
ISBN 0-201-72683-1 

Learning Cocoa with Objcctivc-C”, second edition 

James Duncan Davidson 
O'Reilly and Associates, 2002 
l.SBN 0-596-00301 3 

riiere is ai.st^ a 2(Xb- page rundem n on Objective-C, right on 
your Mac OS X system ODevefQper/DooimentatiQn/CocDa/ObjectlveC/ObjCpdf). 
You should also consider joining the MacOSX-Perl email list, wliich 
covers QmielBones anti other Peiiish topics on Mac OS X, Send 
email to macosx-subsaibe^perforg to gel started. 

Although Apple (lujvtdes documeniation on the AppKii 
and I'tjundaticjn frameworks, it can be tedious to navigate. 
So, pick up a copy of Hoshi 'Fakanori’s Cocoa Browser app 
(http://homepage2.nifty.com/hoshi-takanori/cocoa-browser). This will 
let you browse the Objective-C method descriptions in a 
speedy, hierarchically-based manner. 

As noied above, you will .still have to con veil ihe meihod 
syno[>scs into Perl ft:iriiiai, I)liI that’s life. Actually, I'm actually 
working on a conversion app, liut you'll have to wail until next 
month to read about it. Until then, happy hacking... 
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Danny Swarzman 


TicTacPalm 2 


SuDing Data in a Palm OS Application 


Introduction 

In a previous aitide ( "Tic:TaLpalni: Getting Started with Palm 
OS” in MmTech April, 2002), I presented a basic l^alm OS 
application Fora person to play'I'ic-Tac-'roe against the liandheld 
computer Tltat article presented the struc ture of an application 
and the elements of tire user interface, 1 lere, we ll go one step 
further, adding the ability to save and restore doeumenis. 

On the Palm OS, each application can have one or more 
databases associated witli ii. Our sample application has only 
one datalrase, Fiicii record in the database is a record^ Tlie 
user can review and tmxlily saved games. Tins article shows 
liow to save and restore game records. A Future aiticle wall show' 
how the game data c^an lx.* iransFerred to a desktop computer. 

The Appucaiion 

llclacPalm has three Fonns, a main game Ixiard Form, a gjtine 
list form, and game info Forni. I'he main Form of the appliaition is 
used Ixali to enter new mcjves into a game and to review a game 
record. W use tape-recoixler style buttons to review a game, 
moving Forward or l>ackw%irds. dtiey are visiWe or hidden as 
needed. Figure 1 show^ the lx>artl when reviewing a game. 


TicTacPalm Rpp 





Figure 1: *lhe (Jame Board Form 


The game list fttnn has a scrolling list of names of games. 
Tile user selects a game to open or taps the New hutLon lu start 
a fresh game. (See Figure 2.) As you can see, tliere are buttons 
to open a game and to delete a game. 


Odunt^List 


Cerrm Of^ 


[ Ngw ] ( 0|>afi ] (D^ete) 

Figure 2: (kime list Form 

When the usct deletes a game, the reetjrd doesn't 
completely disappear from the database. Instead, the record is 
marked for deletion. 1’he record is eliminated when the next 
Hot Sync occurs. (We ll discuss tliis in greater detail in antaiier 
article — about conduits.) 

In the game info Ibrm. the user enters the name that is to 
!>e associated with the game. The name drx^sn'i need to Ik- 
unique, dhe program distinguisftes betWK*en games according to 
a record numlKT. 


Game Info 


Gome Name: Game One 


Coin 


Figure Jr Game Itifo Form 

When the user taps OK in this form, control returns lo tlie 
game lx)ard. 

Figure 4 shows how the buiions can Ik* used to navigate 
among the variou,s Forms. Menus could have lxK*n used instead 
of buttons. Menus rextuire more effort to use, but they are 
needed wfien the application is more complex. 


Danny Swamnan writes programs in JavaScxipl, Java, C++, and other bfiguagc‘s. He also plays Go and gn>w.s poiattKS. You can contact him with 
cnninients and job offers at dannys@stowlakcxoni, or you can visit his web site at h[tp^//www.stowlake.a>n>. 
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Lif^ting 1: Declaration lif C!ilctEid) atabase 

class CTlcTacDatabasc 

( 

protected: 

cla^s CTicTacGaffic “taCante: 
static BiRQpenRef sOpenRef: 




cs 


Figure 4: lAnks Among Forms 


public; 

static Boolean OpenO : 
static void Close(j? 
static Ulntlb CountC); 

static void GetGame C Inti6 inReconlNuinbert 
CTicTac Game * out Game); 
static void Sat Gams ( Inti 6 iiiRflcordNuiiiber» 
CTicTacGame MnGame); 
static Lntlb Add ( CTlcTacGamn HnCtime ); 
static void Delete ( IrtLlS inRocordNuraber )r 

CTicTacDatabase {); 
virtual "CTicrTacDatabase () : 


DaIAB/VSI^S 

Creator and Type 

A cLit;itra,se on the Palm OS is a set of mcords as.s(xiateti 
witli a creator and type. A creator is the 32-bit etxle 
correspondiiig to the appiiaUkm. An application can liave 
several databases. 'ITie tylw is another 32-bit code tliat an 
application can use to distinguish among its databasets. 

Records 

A recoi'd can lx* any size up to &4k bytes- Applications in 
wliicli dtxunicnts are laiger must segment the doc'uments. Palm 
OS does have a hie system, which uses the Da la Manager mid is 
not particularly fast. Each rca)rd has flags that are maintained liy 
the Data Manager and accessed through Data Manager functions. 

• 'Ilie deiele flag indiotes tliat the user has deleted a rcccjnJ on 
the Pahn device. When Hot Sync is fxrfoniied. tlie file 
will lx deleted on the desktop machine and finally lx* 
eliminated from the Palm OS device, 

• Hie dirty flag Indioaies that the reccjrd has Ixen nuxlified 
since the last Hot Sync. 

• Hie hnsy flag locks a record for writing. 

• Hie secret flag is cleared only when the user password has 
been entered. 

Game Records 

A [irogram am iipen a record for reading. It can access it 
directly, as if it was just another chunk of meniory. To write to 
a record, the appUc‘:aion opens the reaird for writing. To do the 
actual writing, ii c-alLs a Data Manager routine to copy from 
anoilier memory chunk to the record. 

In this applicatkin, when a nea>rd Is read, iLs data am cx>f>ied 
into a CTicTacGame olijeti. Data am written cop>ing frt>m a 
CTicTacGame ol)iect. Wlten a game is opened, the Ixiard is dispbyed 
with the position as it was when the game was Ixst defied 


Listing 2 shows the funciions to sjive and rcirieve tlie 
cunent game. 


Listing 2: Definition of "GetOame and ::SeiGame 

(TTifTacI^tabast 

void CTicTacDatabase QotGame I Intlb itiRecordNumbor» 
CTicTacGame •outGame ) 

I 

// OiKn liic datubisc 
if { Open(3 ) 

I 

// iitft the numbi^rtd rtuirtt :ukI Nuk [i 
HcmHandle dataHandlia ** DlllGetHecotd ( HOpcttKcr, 
inRccof fJKuKibGr ): 

MemPtr dataPointcr = WeraMand1eLock ( dstaHaadle ): 

// Copy tlic data 

HeioHove ( (void*joutCami!. dataFointor. aheof ( CTicTacGaiie 3 ): 

// Utt1cM:k rclrj.'it Uh; n:cofd 
KcmHartdlcUTtlock ( dacaHfindle ) : 

DibK el ease Record ( ftOpenRef, InRecordNumber. false }: 

// I3t>sc tlu- daiabwi^ 

Closet): 

1 

else 

outGaB]e'>Clcar(): 


void CTfcTacDatabase :: SetGane ( rntl6 InRecofdNunbcr, 

GTic Ts c Ga me * i nCa mo 3 
f 

// 0|>cn ilic dataliasi^ 
if C Open(3 3 

I 

// fict the iitinilKrcd ictonLi and lock ti 

Mi'nsHandle dataHandle - DmGetRecord ( sOpenHef, inRecordNumber ): 
MemPtr dataPointer " MemHandleLock ( datalioiidJe 3; 

// Copy the data 

DnilJrite ( dataPoiriier. 0. InGanie. slzeof ( CTicTacGame ) )■ 

// Uolocfc ick^ase itic record 
MenHandleUnlock C dataHandle ): 

DaReleaseRecotd ( sOpenRef. inRecordNomber, true ): 
ClosoO: 

I 

I 


CTicTacDatabase 

HiLs class handles the database access for the applioiion. The 
declaration appears in listing 1. It handles only one database. 


PRIilERENCES 

The word pn^erences is a Hule misleading. This means that 
the data that is used to store information that the application 
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needs to restore its state- l:ach time the user switches to a new 
application, the newly opened appliaiiion needs tu start where 
it left off the last time the user switched out of it. 

Fi>r example, supprxse tlie user switches out of the applic'ation 
while the Gan>e Info fonn ts displayed, Ute user may have fx.-en 
in the pnKXfss of entering a new name. Tliis p^iitially entered new 
game name needs to reappear wlien the application is opened 
again. 'Hie case is similar for a seleaion made in the sr n tiling list 
in the Game lisi fonn, TjcL’s see liow this cxrurs. 


CTicTacPreferences 

1’he stare of ihe current game is preserved in the application 
database when die application is switched out. This includes the 
state of tile game. Listing 3 shows the declaration for the 
applic'aiion task to deal w^ilh preferences. 


Listing 3: Declaration of CTicTacPreferences 

CTicTacPrcfcRmccs 

i^lass CTicTacPreferences 
I 

protcctcdj 

.Slut ic CTicTacPrcicrences *sPreferences; 
struct PteferencetiKecord 
I 

r tit 16 raCtirrentRecord: 

Intt6 mSetectedRecord: 
ltitl6 ml^eetForwIl]: 

GameNamcTypc raltnconfi rmedNatne: 

I: 

ProforoncGGliocord uiPreferGncesRGrord: 
public: 

CTlcTacPreferencesO : 

^CTicTacPreferences{): 

static Inti6 GetCurrentRccoirdC): 


static void SetCurrentKccotd ( lnij6 IrtRecord ); 
static Intlb GetSelectedKecordC): 
static void SetSelectedRecord ( lntl6 InRecord ): 
static Intis GatLastFont J: 
static void SetLastFotm ( Intl6 inFornID ); 
stattc void GetUnconfirwadKaroe ( GameNsneType outGame ): 
static void Sotancotif t rnicdKamn ( GamcNaneType inGamc }; 
h 


Sequence of Events 

When the user activates anollier a[>plieatioo, the system 
sends an appStopEvent to the current application. I'he main 
event loop picks up the event ant! exits. Conirol gexs (sack to 
TicTaePaimMain, which calls AppStop. AppStop doses the active 
forms. As each fonn is closed, a frmCloseEvent is sent to it. 

AppStop Is defined in Listing 4. Hie hintticin Ursi drmi all 
forms and deletes ilie CTicTacPreferences ohjecl Then it deletes tlie 
olijet.ls iJiat liandle user action. As eadi form Ls deleted, a 
frrrrCioseEvent is generated. "Ilie liandler fw llte form saves tiie 
ojitem state of’tfie fonn in tin* pieferenees daia. Tlien, when AppStop 
deletes the preferences, tite prclercncc data are written Co dbk. 

listing 4: Deftnidon of AppStop _ 

,4ppSmp 

static void AppStop(void) 

t 

// MliIcl' !iurc the fields m cudi liiftti iiit: saved. 

FrmCTostiATlForms {) : 

if £ fPreferences ) 
i 

delete fPrefetencesT 
I 

// DcMruy the wopper i»h|erts for foniLs. 
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If ( fGaraefloardForm ) 


delete fGaceSoardFarini 
fGameBoardForra - NULL: 


if C fGaracrnfoForBi ) 

I 

delete fCameltifoFqina: 
fCaiaelTitoForm • NULL: 

1 

if C fGameLiBtForia ) 

r 

dclere fGaweLifjTFqnn: 
rGamcLialFutin NULL: 


CGamt! I olViForm: :C lt>sc 

Wiien the system executes FrmCloseAllForms, the system .sencis 
a ck)se event to rach lorm. 'Iliis event wOl be prcKessetl liy tht' 
Close funaion for ihe Game Inib fnnii. Ilial fumlkjn, sht)wn in 
Listing 5, saves the partially entered [laine in the preferences, 


listing 5* IK'finitinn of ::Close 

(X iiiniern&iRirm::('JtfSie 

Bouleaii CGiiaelaf oFde n :: CloseC) 

I 

GameNameType na&e: 

GetFieldTcxt I GamelnfoNaffleFieldfield. name ): 
CTicTacPreferences :: SetUncotifirmedNaffle ( name ) : 

// Rcutm falsi! tq tdl the OS tt> clean up the form 
// in the usual way after wc have cKtracted die infu. 
return falnn: 


CTicTacPrefcrences Destructor 

When the data in the CTicTacPreferences object are itplO' 
date, AppStop calls the cleslniclnr for the preferences object, 
wliieh then stores its data, as shown in Listing 6. 


lasting 5: Destructor for CTicTaePrefcrcnccs 

cria^acPiicfefi^ : “(Ttct^til^ficferenccfjt 
GTicTacPreferences :: *CTlcTacPreferences( } 

I 

Boolean saved ** true; //To be lacked up ai IJotSync 
void 'data * (void’)&mPreferencesHecord: 

UlntlS datflSize = sizeof ( PreferencenRecord ): 
ProfSetAppPrnferences (appFlleCreator, appPreflD, 
appPrefVernSonNum, dats, dataSlze, saved 
sFrelerencea NULL: 


Conclusion 

Stt>ring appliaiiion data is relatively easy on the Palm OS, 
as long as the data takes less than 64k. Uestoring the state of the 
application using Preferences data reejuires some tliouglit. Botli 
would Ik' easier if there were an application framework to 
handle the messy details. 

Reffrfw:es anb Credits 

The Palm web site contains tons of infonnation and links to 
related sites: http://www.palmos,com/dev/. 

Thanks to Victoria Leonard for graphic restiurces. Tltanks 
to Bol> Ackerman, Mark Terry and Victoria Leomird for 
reviewing the text. 
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MAC OS X 


Hy Dan Wood, Alameda CA 


Building the Internet-Connected Application 


Integrating the Internet into your Ideas 


Introduction 

You muy have noticed drat iV^ almost impossible lo mn an 
application on Mac OS X without it Hying lo connect to the 
Internet to do something, llie openiling .sy.stem checks for 
u[)dales to iLseif. iTunes cjuerie.s a ciataha.se when you insert a 
music CD, OmniGroup’s applications have a menu that says 
“Check for updates/' The list goes on. 

Taking advantage eif the fact that many Mac OS X 
installations have a permanent (or frecjuent) Internet eonnedion 
is something that you can have your own application do as well, 
even if it’.s not primarily categorized as an ‘‘Inteinet Application.” 
The purjxjse of this anicle is to give you some motivation fo do 
so, and some hints about making it a good exfxrrience. 

Advantages of a Weu‘Q)nnectfd Appiication 

So what are some of the benefits oi‘ an application that 
connects the Internet? Here are just a few : 

• You can make sure that your users are aware of new versions 
of your program being available. Tliis is a great lxK>n for 
su[>pt)it. because you will fiave to deal with tisers of older 
versions of your application less frequently if they are spoon¬ 
fed the newest version. 

• Individual components of your application—plug-ins, 
templates, etc.—can be listed and downloaded directly from 
the application if you maintain a repository of these items. 
WaLson, for example, allows users it) download ami install 
additionai plug-ins directly from the program, rather than 
having to go hunt for them all over the Internet. 

• Data alxmt ihe user (whai version of the application and OS 
she is running, for example) can be ctjIlecLed by a server 


Dumb Servocs 

OK, so you think it's a good idea lo have a server going for 
your desktop application can connect to, hut what if you aren't 
a "server^side” kind of person? Are you going to have to learn 
new technologies like WebObjects or IdlP? Will you need to 
buy an XServe and host at an expensive colcK:ation facility? 

That depends. You can actually accomplish quite a bit 
without any seiver-side programming, and very basic Web 
deployment capabiltries. How's that? just keep it simple, ancl 
put all of your logic on tlie dienl —the desktop program — and 
only data on tlie server. 

Imagine the lollowing scenario^ You want to have your 
program connect lo your server and detenuirie if a new version 
of rile application is available, so you can infonn the user tiiat 
they need to fetch the newest version. One approach is to send 
a message to your server and indtitie the version of the 
application in tliat message. The server would then compare that 
value witli the kncjwn latest version, and tlien either send back 
a mes.sage .Siiying that ihe application is up to date, or a message 
saying that the u.slt needs to upgrade. Tliis, of course, would 
recgiiie programming on the server, 

Whai if, instead, the client application just connected to the 
server and asked for the latesi application version number. The 
client would then compare it.s own version with the number it 
received, and then ilecide whether or not to present an alert 
about application update availability. 

This is the fundamemal dilTerence between a “smarT' and a 
“dumlY server, The dumb seiver can merely Ix" a static file that 
is .served by your Web-ht>simg site of choice. If you’re a CcK:oa 
or Carlion [>rogrammet, you don't need to write code in an 
unfarniliar environment and find an internet hosting service to 
host that .server-side program for you. 

Obviously, the Dumb Serv^er approach w4ll only go so farj 
some tmnsactinns are going to require logic on the server to 
react to parameters sent by the user. But here are some items 


Dan W<x>d cjnce took an intimluaory Arabic da.ss, hut nolxwly in the room knew wUal binguage they were Ixdng lauglil. He likes to buy fruits ancl 
vegetables from the farmer's market on TuescUty nioniings. He imssed tlie last two days of WWDC tliis year due to the birth of his son. He is the author 
of Wasc,>n, an application written in Qjcoa. t>an thanks C^liuck PLsula at Apple for hLs technieul help witli this series, and acknowledges online ccxie 
fragmcnis from John C, Randolph, Stephane Sudie, Ondra Cada, Vince r>eMarcxj, Harry Emmanuel, and others. You cm reach him at dwood^Skarelia.ccjni, 
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that can l)e put into a static file on the server, tiiat ytjur c'lient 
program can react to. 

• Current appncaLii>n versitjn numlier, us iliscussecl above. 
'Hie client compares ti lo its own version and j^rescnis a 
rncs,sage, nm )rdIngly. 

• URL of where to feicli the new version t>f tlie application. 
If an Lipciaie is needed, the client could download the 
update direcily, 

• DescTij>tion of new features. To motivate the user into 
downloading the ut:)grade, yon a7iiltl provide a small list of 
new features, 

• Diiia that inay be needed later in the exeaition of the 
application. If yt>ur pn>gram allows the user lo view a list of 
online downloadable modules, templates, or documents, yt>u 
could provide a list of all available Hies along with the trther 
information, and luck it away until it is actually nee<ietl. 
Such a list could also contain version numbers, S4> your 
ap]>Iicalion could make sure it has the most up-to-date 
versions of the available components, 

• News and status. There’s an interesting way to .stay 

connecled with your user base, by providing a bit of news 
that might display each time the application is launched. 
It could be a “lip t>f llie day'’ that you maintain on the 
server; it could be a holiday greeting, it could be links to 
relevant Web sites. 

You could even provide different variations of tlie 
information you provide, so users ninning your program in 
“demo" mode will view one type of infonnaiion, while your paid 
users get different ditta. Or your data tx)uld depend on the OS 
version used so Mac OS X 9 users will see one message wluie 
Mac OS X users gel a dilTerent one. You ct>uld either pur all 
varianLs into a single file, and let the applicatit>n pick out the 
apprO|)riate j>iei’t‘; or you could have the application access 
dilferent URLs depending on that status. For example, you 
might serve up two files on your site, and your ai>plicaiion 
would fetcli the appropriate one 

• http://www,iTtykillefapp.com/he!lo_unregistered.xml 

• hltp://vvww.rTiykillerapp.corTi/hetlo_fegistered.xml 

If your application is to Ix^ loealized into different 
languages, you could also Icxalize your messages as well. Tlie 
client would request a file based on the user’s primary preferred 
language (e.g. *‘hello_fr" for a French version). If that file 
doesn’t exist, the client would then lay again with the secondary 
language. If you don'i think you'll lx* ctmstanily adding new' 
languages, you might want to put a limit on the numlxr of 
attempts for your client to try, and store the best available 
kinguage us a preference for the next time through, 

Smakj' Servers 

you think yon need a little bit of logic on the server? 


Welcome to Lite world of client-server programming. You 
will need to determine just how much logic is going to go 
into your server and what kind of stiftware and hardware you 
wilt need to run it. Unless you are building an application 
with high bandwidth and database needs, you can probably 
get by with a simple setup that Ls hosted on a service that 
costs about $10 per month and provides ,server-side 
capabilities sucli as PHP and Myi>yL or Postgres. Macintouch 
has some u,seful links at the Following URL: 
http://www.rnadntouch.com/ciotmacalt.htmi. You could get more 
sophisticated with WebObjects or other technologies, 
deployed on colocated hardware, but that is way Ixwond the 
scope of this article, 

A smart server hiLs a number of advantages; it can provide 
whatever information Is appropriau,* to the parameters given in a 
recjuest; if it is told your opentting system, language, registration 
,status, etc., it can deliver exactly tlie mess^igc yon wish to 
deliver. It can deliver personalized, targeted infonnaiion, as 
well For example, your client application could send a request 
for a “Web postcard" to be sent, and provide the recipient s name 
and email address; your server could build up an image and 
email the postcard. This wouldn’t lx* possible without some 
iogit‘ on the server. 

User Iism^RAcnoN 

If you are building Internet connectivity into your 
application, you need to make sure that the program 
behaves nicely. If the u,scr doesn't have network 
connectivity, they might just l>c on a PowerBook, or they 
may have chosen to disable net access, pcrlia|>s if they are 
on a dialup connection. Just fail gracefully; you will 
probably have the opportunity to connect to the server later. 
Your program shouldn’t nag the user loo much if a new 
version is available; allow the user to stop leliing you about 
tlie updates, or only show the reminder every so often. And 
don't initiaie big downloads without the user's permission. 
They may lx* on a slow connection, and prefer uj download 
ihing,s later. 

Getting User Data 

h may be useful for you lo pay attention to usage 
patterns of your application, Pkher for praciical purposes, 
or if you are just curious, it can be useful to know stjmeihing 
about your users, such as what version of the applicatitin 
tliey are using, or what version of liic OS they are on. A 
“smart" server cijuld take parameters passed from the server 
and add those data to a database. Even if you Ye just using 
a dumb server, you could perform some analysis on your 
web logs. 

Be careful alxiul privacy concerns! It is possible lo have 
your client read user in forma tk>n (name, email) from the 
sy,stem sellings, get addre,s,ses and [kitmc numbers out of the 
address book, upload files in the user’s home directory, and 
all sorts of unspeakable acts. The u.sers of your program need 
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to niist rh:it you aren’t writing “spy-ware." You sliould he 
with iiic [>rivacy statemeriLs in your program, and if 
your program does upload any information about individual 
users, you should be ver>^ clear about fiow' that informaiion is 
used and stored. 


Anticipating FinriRE Nffos 

In erealing your interaction model between your client 
and your servei; you Jieed to think about tlie directions that 
your application might he going, even if you dfin'E plan on 
implementing any of lliese features for a while. Keep in 
mind dial tliere inay be thousands of users hitting your server 
for years to come^ and they may he running version l.O of 
your soflware. 

For example, you nughl w^ant to include su[>port for paid 
application upgrades. If you might w^ant to charge a certain 
amount for version 2.0 or 3.0 of ytntr program, you might want to 
]>rovidc upgrade i^rice tiata, even if it won’t lie needed for a while. 

Consider the pos.sihiliiy that your seiwer may temporarily 
he unavailahle to your users. What are tiie rami Heat ions of 
that?' You miglu want to prtwkle a ixiekup server" URL in 
your application to tiy if the primary server doesn't work. 
Kven if your primary sender were ""smart/" you could have a 
backup server be just a static web page indicating system 
status, so your user w'ould automatically get the latest news 
about your server if they were to connect and your primary 
.server mm unavail aide. 

Another consideration is your servers clianging LIKI.s. 
Imagine that you expand so much that you need to move your 
.server, currently on ycair liome 11^ address, to a different domaii't 
or subdomain. If you provided for a ‘forwartling address^’ in 
your server response, you could easily move people to your new 
domain. You sliould consider setting ui:i a different subdomain 
to handle your server-side requests (even if it’s just the same as 
your w^eb server domain) so you could split it into a different 
machine in the future. 

Finally, be sure to think about version compatibility 
betw^een any plug-in or document files you may serve to your 
users. If you provide pkig-ins, but your API changes between 
versions of your applications, you want to make sure that your 
users don’t download plug-ins that won’t work w'ith yonr 
curreni application. If you rniglu have a paid upgrade in the 
future, you wnint to make sure that users of your earlier 
versions of your program can still access their version 1.0- 
compatilde plug-ins. 

InTORMATION PROTOCOI.S 

Now that you have detided to include some Internet 
connectivity into your appllctUion, how should you go about 
tran.sfLTring information liack and forth? 

Before going niLich fuitber, you sltould rx>nsidcr firewall 
issues. Most users have nrj prol>lein accessing Web sites through 
Furl BO, so unless you have some compelling need to do 
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Otherwise, you might as well go dirough that [x>rt. Naturally, if 
you will be tnmsntitting confidential infonnation, yoifre l^etter 
off using SSL 

And unless diere is a need for any real-time or ofx^n- 
ended connectivity, is a great protocol for simple 

retjiiesl/response transfer. Your client makes a request, 
possibly sending some information along as parameters, and 
your server responds with what is effectively a Web page. 
Your client could perform a POS'F or GLr- a GET is simpler 
because you can build up a simple URL of the form 
http://www.host,com/filepath?parafn 1 -value 1. (Be sure to 
‘"escape” the special characters so that your URL is formed 
legally!) In Cocoa, you w<)uld just use NSURLHandle to fetch 
tile contents of that UKL, (If you need to use POST, Cocoa 
developers will need to dip down into Core Foundation or 
make use of CURLHandle (MacTech, Feb, 2002), available at 
hltp://curlhandle,sourceforge.net/. 

Hie response that your server returns should 1^ formatted 
as simply as possible. You could return irfML or plain text, but 
that would retjuire some parsing on yuur server’s end. You 
could return any XML format of your choosing, and your client 
would then parse the XML stream. 

One trick ihai makes ii especially easy for Cocoa 
applications to get at the data returned from the server is to 
format the file on the server as an XML projH^riy list! Even if 
yoiir server is running Linux or Windows and knows nothing of 
this fonmt, there’s no reason why you caii'l place a "f^list" file 
on your web server anti have that streainetl to the client. You 
could maintain ant! etlir this file on your Mac, to make sure it’s 
a readable formal, and then upload it to yt)ur server when il 
changes, (.See Listing 1 for an hypothetical example file. Note 
that we are able to place arbitrary IflML wiiliin our XML by 
summnding it witli the clfCDATAl ... ]]> directives.) 

Listing 1: pc>pcorn_hello.xml 

<7xm1 ver.9Ion-"1.0" fiicoatng"^'*UTF 

CIDOCTYFE pllst PCBLIC " //Apple Conputet//UTl) PLIST 
i .0//EN” "littp: //www.apple.coni/DTDs/PropertyLi£it -1.0.dtd”) 
<plist verslon="L0'‘> 

<dict> 

<key>Cui:rfiTitAppVerElonNiimbt^r</koy> 

<etrlng>1.0.?</Ktring> 

<key)CurrcntAppFeatureii</ki?y> 

<iilririg>This update adds aound effects, and fixes a ctash 
when searching in Japanese.C/string) 

<!- Bcluw is only shown to urvrcgi-sicrcd iiscni -> 

<key>Unregistered News</key> 

<EtritiE><! [CBATAl 

<£otit face^’^Lneida erande'^>Thanks for trying out Popcorn! 

<p> 

Be sure to try out the new <b)Garlic Butter</b> module from 
the <b>Popcorn &gt; Install More Plvig'ins.. .C/b> menu. 

</font> 
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n^’^/Btring> 

<J“ tklow is only shuwti ttj RE(iJHTEHPi) users -> 

<k#y>Regi*irerf!(l NcwB</kcy> 

<.-;trlng><ftCDATAt 

<font !ace="Lucida Graiide''>As a thank-you for our 
registered users» we are offering free downloads of 
<a href=*’hT:tp i //www. karelia .coin/peaniitbutter/">PeaTiuTBuTTer 
l,0</a> for a limited time* Give it a tryt 
</font) 

nX/atrtng) 

</dict> 


TIk* client application can conven the ckm\ stream it 
gets from the server into a Ccx;oa olijeci (gcncnilly an 
NSDictionary or NSArray) by adding this category method to 
NSData, shown in lasting 2. (Constructing the @interface section 
is an exercise left to die reader) 


Listing 2; NSData+plisLm 


propcrtyU stFminXM l 

a prctporty tlsi givro XMt. diia rrtrifvrd from ^ srmT 

^implemetilotion NSDatet pllst ) 

// Rotum 4 pm)H.Tt> ElM rnnn iln; Uat4, t'anokim himiJady a> 

// INSDkilonaty dkLkjitiryWlihCJoriiL'nLsi>fl1ie:pathJ 

- (idJpropertyLlstFroniXKTp 

I 

CFPtopctiyLlsLRel pList; 

CFStringRcf ertorString - nil; 

pLifit ^ CFPropertyiifitCreateFromXMLDataC 
NULL. 

(CFDataRef)gelf, 
kCFPrope rtyl. t Bt T mmu r abl c, 

AerrorSrring); 
ifCerrorString) 

I 

NSL[3g(@"En:or loading from Property List; %$'. 

CNSString*)errorString); 

CFReieasetfirrorSttlng); 

1 

return f(id)pLlst eutorelessel; 


CONCLUSlOW 

'T'hat about wraps up our little discussion oti Internet 
connectivity. There are many tJlher avenues that cxnild be 
explored hy innovative developers, but willi just a little bit of 
work, it's possible to keep your users up-to-date. 
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By Brent Simmons 


Writing Contextual Menu Plugins for OS X, 
part 2 


Running Unix commands and handling 
text selections 


(n pnii one of tliLs ;mide (August 2002) we l>uili u siiupic OS 
X conlcxlual iiicuu plugin that works in the Tinder and provides 
a Copy Path commiind. H demonstrated the Ixisks of iniplemenling 
the COM-hased interfaces for contextual menu ]:ilugins* 

In til is article we wont revisit the COM interface or other 
basics of contextual iiienu plugins—instead W'e1l go furilitT, 
show how to mn a Unix command from a ctmlexiual lueiui, how 
lo send an uptlalc event to the Finder when a file changes, how 
to handle text selections, how to create a siihmenu with multiple 
commands, how to open a UliL in a browser, anti morc\ 

The project file and source, buili using the OS X 10.2 
Developer Tools, can be downloaded from 
http://rancheroxom/downioads/maaech/SamplePlugin.sit. 

Plugin Ovtirvtew 

'This plugin (imaginatively named SamplePlugin) will 
provide ihree commands: 

1. Touch—wlien one or more Files (or folders) are selected, 
a Touch command will appear in the contexaial menu. Ii will 
am the Unix touch command, which sets die modification dale 
of the selected files to the current date and time. 

2. Copy—when text is selected, this command will appear in a 
Text Samples submenu. l\ copies the selected text to the 
clipixiard. (Note thai while some a])pliailions already supply a 
Copy command in ilieir contextual menu, many not, and it's 
useful to have this command.) 

3- Search with Google—wlien text Is selected, this command will 
appear in a Text Samples submenu. It runs a search for the 
selected text in Google in one's defay it Web bniwser. 


Touch command 
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Figure 1 Touch cominatui in Finder's coniextuai menu 

Tlie examineContext function in the plugin Ls called to give 
the plugin a chance to add coinmiuids to the contextual menu 
that's alxuit to l>e displayed. This plugin docs one of three things: 

L It adds a Touch conimand i( one or more hies or folders 
are selected. 

2. It add.s a ^lext Samples stihmenti, with Copy and Search 
with Google t:ommand.s, if text is selected. 

3. It adds nt> commands if neither files nor text is selected. 

iJsting 1: ctiecklng the context _ 

{:X3nim<kHiLc:xi 

static OSStatus exafflineContext (void Vplugininstanco, 


Brent Simmons is a Seatile-ba.sed independent Mac CXS X tlevelopcr and writer He runs a Mac developer news weblog at ranchero.com; lie can be 
ajiitacled Jl brent®ranchcro.cone 
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CO US I AF*I)csc * context, AE&escList 'comiiiainil-lstj 
t 

if (IsFileOrListOfFncs CconT.ext}) 
addFileCcTODandsToHeou Cconunaodlist); 
else if (isTeitSelectiDn (context)) 
addTextCommandsToHenu (comtaandList) i 
return (noErt): 

1 

examlneContexl firM tliciks to .see if one or more Files or 
Folders is selecLed. If so, it adds die File cotnmantls (the Touc h 
eomrUiiiKl) to ilie eontextiud menu. 

If the selection is not Piles or folders, then it checks to see 
if text is selected. If stj, then it adds the Text Samples submenu 
and tlte Copy and Search widi Google commands. 

If neitlier of the alx>ve are I me, it just returns noErr, having 
added no commands lo the contextual menu. 

Tl^e check to see if files are seleaed first checks lo see if a 
single ttle or Folder Ls selected. If not, dien it checks to see if 
multiple fifes or folders are selected. 

Listing 2i checking if files arc selectccJ 

ifiRld>rlisiOnik‘s 

static Boolean isFileOrListOfFiles (const Maesc ‘desc) 

I 

if (iaFileOrFolder (desc)) 
return (truo)i 

returrii (liitaecOfFilos (desc)); 

I 

isFileOit’older c’hecks a single AEIX^st Hr see if it refers lo a 
file or folder. 


Lifting 3: checking an AEDese to see if it’s a file or folder 

jsFWcOrf'uldcr 

static Boolean isFileOrFoider (const AEDcsc ’desc) 

I 

roturn (descIfiOfType (desc, typePSRefJJ: 

I 

If the descritxor type Ls of typeFSRef, or can lx: cocTced to 
typeFSRef it's a Pile or folder, and .so it retums true, descIsOfType 
[>erfoniis thi.s check. It's general—^it can check for tyjx's oihc^r 
than typeFSRef. (In fact, ihis plugin also calls descIsOflype lo 
check for a Icxl selcciioii.) 

Listing 4: checking the type of an AHDe?>c 

destlsonypc 

static Boolean descIsflfType (const AEDese 'dese* 

OSType deelredType) 

I 

AKDosc terapdnsc ItypeNtill, NULL): 

if {(‘deac1*doscriptorType desiredType) 
return (ir«e)r 

if (AECoerceDeac (desc. desiredType. 6(L0mpdosc) 

“ noErr) i 

AHDisposetiesc (&tempdesch 
return (true): 

\ /Mf^/ 

reiurn (raise): 

I 


Why check for typeFSRef instead of type Alias or typeFSS? 
Bc‘cau.se Apple’s message is that FSRefs are the way lo go in OS 
X. It would probably work as well to suhsiituLe one of d)ese 
other types—but when your platform vendor tells you to do it a 
c:erLain way, IPs prnlxibly a good idea to li.sten. 

lists of files 

If it's not jusi one file or folder selected, isRIeOrListOfFiles 
next checks to see if it's a list of Files or Folders selecLed, 

isListOFFiles loops Uinxigh eacii item in the AEDescUst 
and calls IsFileOrFoider for each item. If any call.s to 
isFileOrFoider return false, then the .selection tlicrefore 
contains items other than files or folders, and so isListOFFiles 
retums false. 

Listing 5; looping through a Ust 

LiLifaQOnk^ 

static Boolean isListOfFiles (const AEDese' dcoc) 

I 

long numiteiEE. i: 

OSErr ern 

err = AKC«^untIteiiis (desc , ; 

if (err != noErr) 
return (false): 

for [i “ 1; i <- numlteins: 1-H- J 1 
AEKcyvord keyword; 

AEDosc rcppdesc = ttypeKull, KULLI: 

Boolean fU'ile "" true: 

err ^ AEGetKthDesc (desc. i. LypcWlldCard, 

&k eywo rd, &t eaipd esc) j 
if (err != noErrj 
return {false); 

flFlle = ieFUeOrFolder (Atempdesc); 

A£DlsposeUe:sc (il CMpdenc): 
if (IflFile) 
rerum (false); 

\ 

return (true): 

1 

AECountItems gets the numIxT of items in the list. Then a 
for kMjp visits e-ach item, calling isFileOrFoider with each. If 
isFileOrFoider retums false, llien isUstOfFiles retums false. 

Oilierwise it leturns true, and then isRIeOrlistOfFiles returns 
true, and we’re back to examineContext which Eiicn calls 
addFileCommandsToMenu lo add the Touch command to the 
coni ext uiil menu. 

Adding the Ibuch menu command 

Po add ilie Touch command, ihi.s function calls 
pushCommand with the title of the comma nth its command ID, 
and die command list that will Ixcome the contextual menu 
that appears. Ttie final jjanimeter sent to pushCommand is 
NULL—if diis item had a submenu it would be specified in the 
last parameter. 

Listing 6; adding tiie localizable Touch command 

adilFiid ^ummandsToMenu 

fltailc Boolean addFlleCommandBToKeou 
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(AEDescList •commandList) 

t 

CFStringRef touchComftsnd * 

CFCopyLocal1zedSt r tng (CFSTR("Touch*), 

"Touch Rfinu Toni"): 

roturn (pushCommand {touchCcmiitand* touchCoimsndTD. 
c ontma ncLLi st, NULL) j: 

I 

Note* iliai ii gtiis I he name of the Ibuch exjimnand hy 
calling CFCopyLocalizedStfing. Tins looks up ihe name in 
MenuNames^strings (a resource that's included with the projeci 
you downkxided)* This way you can easily localb.e the plugin 
by editing a strings file—wliieh is dttfinitely preferred to hard- 
exxiing the names of menu itenis in die source c'ode. 

We’ll otherwise skip pushCommand for now—well talk 
alxiut it later when we show how lo build submenus. For 
now just know that it adds the Toueli command to the 
contexlual meniL 

louchCommandID is defined in SamplePlugin.h. The 
command ID, since it's just used internally, does not have to lx? 
loc’alized, of course. 

After this function returns, examineConlexI returns nol-rr, 
and the system handles displaying and tracking the 
coniexmal menu. 

Handling a command 

handleSGlection is called by the system to actually nm a 
coiiunand cluxsen by the user. 


lasting 7: handling the user’s command _ 

hindlcSeJ«:tk>n 

static OSStatus handleselactIon (void •pluginTnsiance, 

AEDesc ‘context. SInt32 commandTD) 

I 

switch tcommandln) I 

case ioiiehConttaandlD: 

ruiiTouchCommand (context): 
break: 

case copyCommandID: 

rnnCopyCoimnand (context); 
bresN: 

case searchCommandiD: 

runSearchCommaad (context): 
break: 

I 

return (noErr); 

I 

Based on tlte command ID associated with the given 
command, it calls the corresponding funcTion, If Touch is 
chosen, it calls runTouchCommand. There are similar cases for 
the Copy and Search with Google commands (more aUrui 
those later). 

Running the Touch command 

The gtral of this Func'tion is to pass to tlie system a string of 
text as if ty|>ed on the coniniand line. We’n:? callmg the Unix touch 
command with one or more files or folders as aigunienis. The 
siring that gels passed to the system will look something like this: 
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/usr/bjn/louch "/path/to/some/file" "/path/to/some/ottier/file" 

Biit:h separate file path Ls enclosed in quotes because there 
may be spaces in the name. 

So the hrsi thing runTouebCommand does is get the list of 
selected files as a siring suitable for pa.ssing lo the system as 
command line arguments. 'Ilien it actually calls the system to run 
the touch command. Finally ii sends an update event to the 
Finder so it updates its display. 


Listing 8: running the command 

mnlcHichOinmiand 

static void runTouchCommand (con^i AEReec ’dcflc) 

( 

CFStrlngRef cofumandLlTiaPar^iiis; 

If 11 getFl leLlstAfiText BicOMniaTidLineFsranis)) 

returiK 

callSystetB (CFSTB("/uRr/bin/toudi"). commandLlncFarams): 
CFReXeasc (commmdilneParainjs); 

£endUpdateRv«!jtToFltidet (dei>c); 

I 


getFileListAsTexl Is somewhat similar !o the isListOfFiles 
funtiicJti—it loops through the selected files in the s;iiiie way. It 
also double-checks tliat each item actually is a file or folder. 

listing 9: getting tlie list of selected files as text 

l^inPik'UsiAiiTfxt 

static Boolean gelFi 1 cl.iRtAsTcxt Cconst AEDesc 
CFStringHef 

I 

long nuMitesia, I: 

OSEtr err; 

Boolean flSuccess false; 

CFMiitableStritigRef e “ CFStringCteateMutable 
{RCFATlocstorRefaulty 0); 

if {b = HULL) 
return (false); 

err “ AECountltems (desc* iinuinlLoiitii) i 
r 0 quire_noerr (err, getFileListAsTexi_fail); 

for (i = ]: i <“ numiteiBs ;!■<■+) I 
ARReywo rd keyword: 

AEDesc teinpHcsc " ItypnNulK HULL I; 

Boolean HFile " fnlsn: 

err = AECetNlliUcsc {desc, 1, typeWiIdCard, ^keyword, 
&tempdesc}: 

require_noerr (err* getFlleListAsText_rai13; 

fiFile ^ ftcrepdesc.descrlptorType = typeFSRef); 
if (inFile) ( 

orr = AEnn<!rceDesc (Steapdesc, typeFSRef* 
iletnpdesc); 

require_i(uerf (eir. Fit cLLKlAsText_ rail); 
flFile {tenjpdesc.descriptorTypc ” typnFSRnf); 


if (IpiisbFileAsText C&terapdesc, s)) 
flFilo - false; 

AKDispofseDesc (Atempdesc): 

If (iflFne) 

return (Inlse)I 

) 

flSuccesfi * true: 

getPlleListAsText fail; 
tf (FI Success) 

•TilcLiSt = CFSt ringCreateCopy 


(kCFAllocatorDefault. s)* 

else 

•fileList = NULL: 

CFRelease (s); 

return (fiSuccess); 

I 

One of the parameters, fileList, is a pointer to a CFStringRcf 
that w ill contain the lust of files as qiJote-ent:lo.sed aiguments. For 
each item, pushRleAsText is called, which adds each item to a 
CFMiitableString created at the top of this hmetion. 

At the end of the function the CFMutableString is copied to 
the fileList parameter, whkfi is a non-mutable CFString. O'hat is, 
if everything went well. In case of a problem rhe fund ion 
returns false and fileList is NULL.) 

Adding a single file to the list 

pushFiieAsTexI takes one AEDesc that references a file or 
(older, gets its Unix path, escapes double quotes in the path, 
escapes $ characters in die paLti, puts dt>uhle quotes around 
lire pa ill, adds a space, then adds the texi lo die passed-in 
CFMutafdeString. 

Listing 10: adding a single file _ 

pnjibFileAATcxt 

static Boolean ptl^^hFi 1 cAsTfixt (const AEDese ’deec, 
CFPtutablcStringRcF s) 

1 

CFStrinpef pathStringp cscupcdPalhSi rl na; 

if {iBcrPathStrlnftFromFSRef (desc« bpathStringJ) 
return (false); 

if (fescapeShellTcxi (pachString. iescipedPathStriog)) I 
GFReleasc (pathString): 
tettirn (false): 

1 

CFStringAppend (s, CFSTR{: 

CFSrringAppend (s* eecapedPathString): 

CFSi ring Append £s, nFSTR£"\" M)* 

CFRelease (pa UlSu i ng) : 

CFRelease (escapedPaLhSLring): 

return (true); 

) 

ll calls getPathStringFromFSRef lo get the [ralli lo the file as 
a CKSiring, 

Then il escapes quotes and S characters inside die padi 
string—if there are quotes anywhere in die [latli they must lx* 
esca|xd, otherwise diere would ix quote mis-malches in the 
eommanti line text. S charatlei^ must lx escifxti to avoid 
varialde interpolalion. (For instance, rf ytni liad a file named 
$USEB for some stntnge reason, the system would replace 
$USER with your actual user name. We don't wanr ihai to 
ha[)pen here.) 

It then adds a quote to the mutable siring, then adds the 
esciped path, then adds anodier quote and a sp;ice. You end up 
with a siring like ™/patli/io/some/iile'' or Vparh to some/file” t?r 
"/path to/\$soiTie\" file/." 
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Getting the path string 

getPathStringFronriFSRef gcLs a Unix path string from an 
rSRcf and puts it into a CFString. 


Listing 11: getting a path string from an FSRef 

RctPiithSTrin^FfiimFSRff 

static Bogiean getfathStrlngFronFSHef (const AFEJesc 'desc. 
CFStcingRef *pathstring) 

I 

nUf fileRef; 

datflStEfi * (desc); 

OSErr nrr; 
cmucf rnoURL: 

err = AECetDescOata {desc. dataSlsie): 

If (err noErr) 
return (false); 

filetlEL ■ CFURLCreateFroitiFSRef (RCFAlIocatorDefault. 
AfiUSefh 

if {fiteURt. -- mJI.L) 
return (false): 

‘pathstring - CFURLCopyFileSysteroPatb (flleURL. 

kCFlJRLPOSlXPethStyle): 
return (‘pathStrlng != *JULLJ: 
t 

First it geLs llie I^Rtf object from tlie MDesc liy culling 
AEGetDescData, CFURLCreateFrofnFSRef gets a CFDRLRcf from 
The FSHef—and from that it gels the TJnix-style path by calling 
CFU RLCopy FileSyslemPath. 


getCFString is a simple wrapper around 
CFStringCrealeWithCString, wliicli creates a CFString based on 
a C string. 

Escaping text for the cofumand line 

Hack to pushRleAsText: it next calls escapeShelfText, It does 
a couple Find-and-replace nper:iiions in a CFSiring. l! est:apes 
tiouble cjuotes and $ charuclers to avoid i|LJOie inis-matches 
(wlien a file contains a double quote in its name) and variable 
interpolation (on the off chance you have a file named 
something like SlISKR). 

Listing 12: escapeShellText ___ 

cscaiK-shcUTcxt 

static Boolean escapeShellText (CFStringRef source. 

CFStringRcf ‘(test) 

I 

CFSiritigRef tcttipSt ri 
Boolean TlSuccess = fnlsc: 

If (IrepIaceAll (CFSTR(n*"), CFSTRCnW""), 
source* &tempString)} 
return (false): 

nsuccesa = replaccAll (CFSTR(-S")* CFSTK(n\$’-) * 
TCflpString* dest); 

If (ftSuccess) 

CFReleaSe ItempSlring): 
return (flSuccess ); 

1 

raplacGAII acrually performs the replacements. 
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Listing 13 ; replaceAll 

rqilaccAll 

Static Boolean replaceAll (CFStringRef searcbFor* CFStringRef 
replaceWith, CFStringRef source. CFStringRef ‘dest) 

[ 

CFTiutableStringRef mutableString: 

CFRange range; 

rautablGString = CFStringCrcotoHutableCopy 
(KCFAlXacaLorDefaull. 0. source): 

if (mutableString = NULL) 
return (false): 

range = CFRangeMake (0. 

CFStrlngGetLength jmutableString)); 

CFStrlngFiudAndReplace [mutahleString, searcbFor, 
repIaccWith, range. D): 

'dest ^ CFStringCreateCopy (kCFAllocatorOefault* 
iButableString) : 

CFRelease (mutableString) : 

return (*dest != NULL): 

1 

The first paniiiietcr La reptaceAll is llie striii|r to find, the 
second parameter is the replacement strin^^, the third jyammecer 
is ihe source string in which lo search, and the last parameier is 
a [jointer to a CT^SlringRef tliat will contain the result. 

Aside: CE Strings 

Question: wiry use CFStringRefs and CFMulafjleStringRefs? 
Why not traditional C strings or Pascal strings? 

Because, as with FSRefs, Apple’s message is that CFStrings 
are the way lo go. But beyond that they have .several benefits: 

L Tliey’re easy lo inani[)ulaie. functions like 
CfStringAppend make it very easy, for instance, to add text to a 
string. Check out CFString.h—there is a gold mine of functions 
which make string manipulation easy. 

2, Cl'Strings are “toll-free bridged" with Cocoa NSStrings. 
d'hj.s means rbag amfjng other things, when writing Cocoa code, 
you can call CFString [unctions with NSStrings as parameters. 
'I’his is an example of a kind of convergence, where you can 
WTite code that works in Carlxm apps as well as Cocoa apps. 

3. CFStrings lake some of the lieadaehe out of supporting 
various character encodings. Support for Unicode and otlier text 
encodings is m important parr of a modern operating system, 
and CFStrings can store Unicode text as well as other encodings. 

Back to ninTouchConimand 

Now ifs time to actually call the s 7 slem to run the Toiidi 
command. 

If getFileListAsText succeeds, runTouchCommand calls 
callSystem, which takes two parameters: the path to the 
command to execute and tlie comjnand line parameters (as a 
single string). 

The path to the Touch command is /usr/bin/touch. The 
command line parameters in this erase is the list of hies created 
in getFileUstAsText. 


Note the line (in rynTouchCommand): callSystem 
(CFSTR('7usr/bin/touch''), commandUneParams); 

'I’he CFSTR(’Vusr/bin/touch'') part is a shortcut for creating a 
CFStringRef from quoted text. (Cocoa developers will note that 
ifs the equivalent of typing @7usr/bin/touch" to create an 
NSString.) 

Calling ihc system 

It's simple lo call the system lo execute <i command-line 
string. There’s a fimction acTiially named system that takes a C 
siring and executes the command as if lyped in the Terminal. 

rnie man page for system is pretty^ short and worth 
checking out.) 

Listing 14: calling tlie system 

caUSy&ton 

fltarfe vatd canSy£?rr‘in (CFStringHef command, 

CFStringRef pa rams) 

I 

char ‘buffer; 

CFMutableStringRaf fullComniand: 

fullComiiiand “ CFStritigCteateHutableCopy 
CkCFAllocatorDefatilt. 0. command): 

If (fullCommand = HULL) 
return: 

CFStringAppend (fullCommand, CFSTRt" ")); 

CFStringAppend (fullCoramand, pacams): 

if ([getCString (tibiiffer, fullCoiiiTnand. 
kCFSrringKncodingUTFS)) 
ca 11 SyHi rin_ex i t; 

prinLt ("System call: : 

printf (buffer): 
prititf ("Vn”): 

fiystem (buffer): 

cailSystotti_ox{t: 

C KHe 1 e a s e (full Contina nd): 
if (buffer != NULL} 
free (buffer): 

I 

Our callSystem function takes two Cl'StringKef parameters— 
the p:irh to the command and the command-line para meters. In 
cjrder lo call die system command ii needs to create a C string of 
this fonri: /path/to/command parami param2 paramS. 

In Uiis plugin it will look something like this: /usr/bin/touch 
7palh/to/f!le1" 7path/to/anotherFile" 

Tlie fiillCommand string is a mu table CFString. It staits by 
copying the command (the /usr/bfn/touch part) to irseli’ 

Then it appends a space, since there needs Lo be a space 
Ijctween the coinmand and the parameters. Then ii appends 
the parameters. 

At this point we have the string in the right form for the 
system, except that ids a CFString ratlier than a C siring. So it 
calls getestring to get a C string. 
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listing 15 : getCString 




static Boolean getCString (chat **cSti:ingToGet, 
CFStrlngRef cfString^ CFStrlngEncod1ng encoding) 
t 

tJInt32 lenTcxt ^ a I zoo f (Uni Char) * 

CFStrJngGctLcnglh (cfString) + i: 

*cStritigToGet “ malloc (lenText); 

if (‘cStrlngToGet — HULL) 
return (false); 

if CiCFStrlngGetCString (cfString, ‘cSLrlngToGet. 
lonTpxt* encoding)) [ 
froo (‘cSirlrigToGetJ : 

‘cStringToCet - NULL: 
return [false): 

I 

return (true): 

I 


‘I'his function is a wrapjw for CFStringGetCString. which 
gcLs a C siring from a O’String. First this functk>n alltK'atcs a 
l>uffcr that's the Icngiii of the CFString plus one for Zero- 
Termination. I'hcn it calls CFStringGetCString. If that call fails, ihe 
buffer is freed and the function returns false. If alFs w^ell it 
returns true. 

Back tt> callSystem 

before calling the system function, noiice the trio tif pnntf 
commands. An impentant ptnnt; one way to del>yg ctmtexuial 
menus is to use printf commands. The output apix^ais in the 
Console. (Whic)i lives ai /Applicalions/Utilities/Console.) If you 
launch it, then am the Toucli command from a conicxiuat menu, 
yoiill .see a copy of what gets passed to the system command in 
the Console* 

llioLigh not used here, anotlier iinpt>rtani function, similar 
to printf, is the CFShow command. ITus prints a description of a 
CorcFoundalion objt^cl—.such as a CFString—to the Coasole. 
(See CFShow and CFSliowStr in CFString.ti and in The 
documentation.) 

Okay, m>w ii finally calls the system witli ihe C siring from 
geteString. This nins the Unix touch command wiili die li.st of 
files us pai ameters* 

This function cleans up, then control goes back to 
funTouchCommand, tiien back to handleSelection which returns noErr. 

That’s it for running u Unix command. You know the 
IxLsics —yon c:an do just about anything Llnix-y from a contextual 
menu plugin now, 

Bui it didn’t work..* 

Oh yes it did. But it iiiiglu not have appeared to work. 

Here's why: sometimes the Finder doesn’t update its disf>lay 
right away when you make a change to a file from a contextual 
menu. And m it may look like the command didn't work, even 
though it actually did. 

So funTouchCommand sends the Finder a kAESync event via 
the sendUpdaleEvenlToFinder function: 
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Listing 16: ^tending a kAESyac event to the Finder 

!»cfxll update LvcnribPinikT 

void S(?ndUpdateKv(»ntToFinder {const AEDesc *desc) 

I 

AEAddreasD&sc fioderAddrossDosc = ItypfiNiillt NULLh 
AppleEvent event - I typeNulK HLn.L); 

AppleEvetit reply “ i typeNull* NULLl; 

OSType flnderSignature = ‘HACS': 

OSRrr err: 

err ” AEGreatenese (typeApplSignature, &flnderSlgnattjre, 
sizeof {iInderSigna t u re), 1nde rAdd renaDesc1; 

if (err I” noErr) 
return: 

err = ARCreateAppleEvent (kAEFinderSuite, kAESync. 

1nderAddreEsDesc» kAatoGenerateketurnlO^ 
kAfiyTratiBactionTD* &event): 
requirc_!xoorr Cerr, sendUpdataEventToFindet_fail): 

err = AEPutFaraaiDeiJC (^evenL, keyDi rod Object * done): 
require_noerr {err^ sendlipdateEveniToFindcr_fail2): 

AKSend (&event. Sreply, kAEUoRepiy + kAECanInteract. 
kAHNormalPriority, kAEDefaultTimeout. HULL, NULL); 

sendUpda t e Kven tToFlnde r_fai12: 

AEDieposeDesc t&evonl); 

aendUpdateEventtoPlnder^faii; 

AEDisponeDesc (^CinderAddreasDesc): 

I 

It tTCiUus an Apple event that just asks tlie Fintier to U|xl:ite 
its display. (See FindefRegistry.b for this and other njiiintands 
you can send the Finder.) 

1'his function passes to the Finder, as the direct oiiject 
parameter, the same AF!)esc context received in handleSelection. 
One assumes that the Finder knows w'lial to dt) watli lliis AEDesc 
since it ome front ifie Finder in the first place. 

kAENoReply is s|x*cified, since a reply w'ouldnl Ix" ust^fuk 
and we don't really care if the Finder failed \o liantile the event. 
We hope ii handled the event, hut if it didn’t it's no hig deal, 
since the Touch command succeeded anyway, 

Tex J COMMANDS AND SUBMliNLfS 
kn’s buck all the way iifi to examineContext and show' how 
to add a submenti to the contexnml menu and how lo handle 
oiir two text tomniands (Copy mil Searcli with Gotigie). 

Recall tiiat if iFs not one or more files or folders thiit are 
selected, then examineContext checks lo see if iFs text 11 nil’s 
selected. isTextSeleclion perfomis this check. If the check returns 
true, ihen examineContext calls addTextCommandsToMenu to add 
the submenu and its commands. 



Figure 2 7ex/ cofnmmul'f fw BBFM s corilex!ual menu 


isTextSelection 

'Ibis fundion checks liie AEDesc tliai examineContext got 
from the system to see if it's of type text or can lx coerced lo 
iVfX" text. 

Listing 17: checking if a selection b a text selection 

isTtTjtSc'lcctk»n 

static Eoolean iGTcxtSt^lpjction (const AEDesc *desc) 
t 

return {descUOfType (desc, lypi^Char)); 

I 

typeChar, defined in AEDataModel.h. is 'TEXT.' Tliis function 
calls descIsOfType, w'hich was also called hy isFrleOrFolder to 
determine if an AEDesc refeis to a file or folder. 

If isTextSelection returns tnic% then examineContext calls 
addTextCommandsToMenu wiih ihe AEDescLisi from the system 
that will become ihe contextual menu. 

Adding text coiinmnds 

Tlie plugin will build a rnenu item named Text Samples 
with a submenu. 'Hie sul>menu will ctmuiin two commands: 
Copy and Search witli GcK)gle. 

Here things arc done in whai may stfcm like a backward 
order. First the submenu (Copy and Search with Google 
commands) is cic'ated, then the menu item is created that will 
contain the submenu. 

listing IS: adding text commands to the menu 

m\i nv\ I (>jmnundsT[) Mt nii 

static Boolean aadTextCoiumatidsToMenU (AKDeBcLiBt* 
conucandList) 

I 

AEDescLfBt subinenuCcuranands - ttypeHuU, NULL); 

OSErr err; 

Boolean flSuccess = false: 

CFStringRef textSubmenulianie “ 

CFCopyLocaliiedString (GFSTR("Text Samples'"}, 

'•Text .Samples Henu Text"): 


err = AEGrcateLifit (NULL, 0, false, AsubmenuCoiimands): 
if (Grr t= noErr) 
return (false); 
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REALbasic® 


REAL Software and MacTech present the REALbasic Showcase to 
highlight some of the fantastic solutions created by REALbasic users 
worldwide.The showcase illustrates the wide range of applications that 
developers using REALbasic can create. Some benefit any Mac user, and 
others are more specific.All of them are seriously cool! 

REALbasic is the powerful, easy-to-use tool for creating your own 
software for Macintosh, Mac OS X, and Windows. It runs natively on 
Mac OS X as well as earlier versions of the Mac OS. For more 
information, please visit: <www.realbasic.com>. 

The Made with REALbasic program is a cooperative effort between 
REALbasic users and REAL Software, Inc. to promote the products 
created using REALbasic and the people who create them. For more 
information about the Made with REALbasic program, please visit: 

<www.realbasic.com/realbasic/mwrb/Partners/MwRbProgram.html>. 







REALBASIC SHOWCASE 



Extend REALbasic with 
Advanced Plugins 


Spreadsheet Controls: 

We provide a wide range of spreadsheet controls for 
REALbasic, Including multistyled and custom rendering 
spreadsheet controls. 


• More than 32k of rows. 

• Classic, OS X and Win32. 

• Accelerated for maximum 
speed. 

• Images in cells. 
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Cryptography: 

We provide data encryption, encoding, 
compression and hashing for REALbasic. 

Supported Algorithms; 

• Encryption: 

- e-CryptIt 

- BlowFish (448 bit) 

-AES (Rtjndael) (256 bit) 

• Encoding: 

- e-Cryptlt Flexible 

- Base 64 

- BinHex 


- MacBlnary III 

- AppleSIngle / Double 

- UUCoding 

• Compression: 

- Zip on Strings and streams (.gz) 

• Hashing and Checksums: 

-CRC32/Adler32 

- MD5 / HMAC_MD5 

-SHA/SHA1/HMAC SHA1 


Other Plugins: 

We have many other 
plugins for REALbasic, 
including plugins to do 
advanced MacOS 
Toolbox tasks and more 
custom Controls. 


Speed up developement and make 
more advanced applications 
by using plugins ! Get free demos 
at www.einhugur.com 

Einhugur Software 
sales@einhugur,oom 
www.einhugur.com 






piPop 

Pop-up flierarchical 
Filci Navigalion and Launcher 


TelnetLauncher 


Bookmark and Launch your 
Telnet and SSH sessions 



SimpleKeys 

Set your Function Keys 
to type stuff for you! 


piDog Software 

http://www.pidog.com/ 



MAC MUSIC MANAGEMENT FOR 
SONV 5 TO 400 DISC CD CHANGERS 


Control up to 12 changers (4,800 music CDs) 
Control Any Brand Stereo Receiver 
Play MP3 and other Sound Files, 

P»us much, much more!!! ^ J 

wvinv.titletraBc!com - mfo@tttretrack.com 
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REALBASIC SHOWCASE 


UniHelp 


Cross-Platform HELP 
Module for REALbasic 
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SUmulin 2.0 


Apple Help Viewer. Micrpsftft HTML Help. WinHelp.... Why waste 
precipus time developini a different Help system for each platform 
when you can easily use UniKelj|for all of them? Compatible with 
Classic Mac. Mac OS X and Microsoft Windows 98-XP. 

^02iCubi^Awafd iWI liner, 


• Displays HTML & Text Files- 

• Supports URL Links, Hdatlve Links, 
Anchors & Email Links- 

• Parses More Than 20 HTML Tags & 
More Than 60 Special Characters, 

• Supports Images. Video and Audio. 

• Built-in Search Englne- 

• Supports Context-Sensitive Help. 

• Hierarchical Table of Contents. 

• Familiar Help*style Interface, 

• GUI Support for 6 Languages, 

• Extremely Customizable. 

• Small Memory Footprint. 

• Easy to Use & Royalty-Free! 



SPECIAL OFFER 

Purchase UniHelp and 
j^eceive a FREE Upgrade 
to the 2003 Release ol 

HelpLogic i.o 

pf^ffelp Auttiorlng Solution 


DOWNLOAD NOW 

www.ebutterfiy.com 








the cross-platform solution 

for Macintosh and Windows 



• build both Macintosh and Windows screensavers 
with a single dick, no matter what system* you are using ! 

• use any QuickTime 6,0 movie formal: 

Macromedia Flash 5.0, MPEG, Cinepak, MP3, Midi, AVI, DV Video... 
or, now with version 3-0, build your own basic Slide Shows ! 


TlieJottrttJf^Madjiiiih St D<etidapmfMi 



Got a great product built 
with REALbasic? 

Promote your product through the 
very cost effective REALbasic 
Showcase in MacTech Magazine. 

For more information, contact us at 

adsales@mactech»com 


* include a hidden movie that can be unlocked 
with a registration code 

• customize and fully-brand both Installers 
and Screensaver control panels with pictures and text 


• Screensavers install without DLLs, extensions, or restarts 


simple 

WYSIWYG 

editor 

supports 
interactive Flash 
and QuickTime 

consistent 
cross-platform 
user interface 

try before you buy 
fully functional 
online downloads 



creating screensavers 
for both Windows and Macintosh 
has never been this easy 

ht1'p:y^lScre>pns»c3V6“r.nG3f 

: irftj @ lScre»€»ri£^«3VPr.rTPf 

* » si Z!0<w, mOirfv 

Mjcmosh OS 8.S tfl uiomwiT 9 MT4yirr?axwxp 

iSCTMKfiMf OHigner vHfton )JD wil MfipaFt t«a Vs moMom IH ir>.2 

Uwta lltALbM-i. 


Janijaky 2003 • MAfThxii 


71 



































































if (tbuildtextSubciejiu {isubmenuConunaTids)) t 
AEDisposeDesc (IksyboisnuCoxiinaDds); 
return (false); 

I 

flSuccess pushCoramand (textSubneniiNaiie. ail» 
conm and Li s t, ^gubaett uC nimnatidg): 

AEDisposeDesc (^submenuCosoDands]; 
return (flSuccess); 

I 

Tiic suliinenu is, like the commandUst passed to 
examlneContext from the system, nn AtiDescUst that will specify 
one or more a>mm;ituk submenuCommands will hold the 
subinuiiu; buildTextSubmenu creates this suhtneniL 

listing 19; building a submenu 

huililTrxtSubmrnu 

atatlc Boolean buildTeKtStiboienu lAlDeRcLiflt ’^roinmandfl) 

[ 

CI'StrlngRef searchConraaful ” ClCopyLocalixedStrlng 
(CFSTRt"Search with Coogle**)* "Search Hetiu Text"); 
CfStringRef copy Command ’ CFCopyLocaiizedStriTig 
(€FSTRC"Copy")* "Copy Kenu Text"); 

if (I pushComniand (copyComnand, copyCoininaTid tD* 
comitand©* nil}) 
return (false): 

return CpushComaand (searchComaiand, searchConaBaivdlD, 
commands, nil)); 

I 

It calls pushCommand mice, with the command names* 
command IDs, and (he AKIX'sdJsl that wall contain ihe cxnnmantk 
If it succeeds, then addTextCommandsToMenu calls 
pushCommand to add the Text Samples menu item that will 
contain the sul7menir. 

Here’s the important point: IhhJi the main comextual 
menu and any ,submenus are AEDescLisis. That means that 
you add commands the same way, whether it’s the main 
menu or any submenus, pushCommand is thus a reusable 
piece of code* useful whether youVe building one or mcne 
submenus or not. 

lasting 20: adding a command to a menu 

pashC^imnuind 

siatic Boolean puehCoranand (CFStringRef conunandNaBie* 

SInt32 coamandlD, AEDescList* commands, 

AEDeacList 'subiiienuToAttach) 

I 

OSStatuf; nrr noErr; 

AERecord commandRecord " ItypoNull, NULLI; 

Boolean flSuccess = false; 
char *coBnniindSaioeCStriiig; 

err * AECreateLlst (NULL. 0* true. AcommandRecord); 
require_noerr (err, pushComand fail): 

If (IgetCString (&ccKninandNatioCStrLng. coinirandNamo, 
knFStPlngKncodingUTFa)) 
goto puahCoffliiitind_f:ail; 

err “ AFPutKeyFtr tScommandRecord* ReyAEName. 
typellTFSText. commandNameCSrriiig, 
strlen (coimnandNameCEtring) f U; 
free (comiBandNameCStririg); 
require_noerr {err* pushComMand_fan): 

if (connaandlD 1= NULL) ( 


err = AEPutKeyPtr CfircommandRecord* 
keyContextua iMenuCotumand ID. 

typeLonglnteger, &coiiiiDandID, si zeof (coinmand ID)) : 
reqiiire_noerr (err* pushCommand fail); 

I 

if (submetiuToAttach NUtT.) { 

err = AEPutKeyDesc (iicommandRocord. 

keyContejttualMetiuEubaenu, submcuuToAl ta ch); 
require_noerr (err* pushCommand_£ail); 

) 

err “ ARPutDobc (comraands, 0* ^rommandRecord); 
if (err = noKrr) 
flSuccess = true; 

puEhCommand_fail; 

AEDisposeDeec (hcammandRecord); 
caturn (flSuccese): 

I 

When using pushCommand to adtl a menu item tliat 
contains submenu, just call it with a NUIJ* commandTD and a 
non-NULL ARDescList that spcciftes the submenu it ctmtains 
tsubmenuCommands, in this case). 

When using pushCommand to add a menu item that does 
not contain a submenu, specify its command ID, and send a 
NULL AEDescList, .since it will have no submenu, 

When addTextCommandsToMenu is finished, control returns 
to examineContext, which returns noErr. Then the sy.stcm tlisplays 
and tracks the tontextual menu with the Text Samples menu 
ileiii and its SLibnienii. 

ilaiidliiig the text comiiiaiids 

Back to handleSelection—if the command ID is the ID of the 
c'opy a>nimand. mnCopyCommand is called. If it's the command 
ID of die searcii coinmaiid, runSearchCommand Is called. Let’s do 
runCopyCommand first. 

The Copy commimtl copies the .selected text to die 
cliplxiard (unsurprisingly). 

Listing 21: ninimig the Copy caminand 

nin(aip)<:omiiM[Hl 

static void rtinCopyCcmiinaEid (conur AEDf^sc *desc) 

I 

CFSiringRcf solectcdTcx;; 

If (tgetTextEroniDesc (dcec, ^selectedText. 
kCFStringEncodingMacRoraan)) 
return; 

-writeSttingToClipboard (selectedText); 

CFRclcasG (uelcctedText); 

1 

First it gets the .selecled lexi from the AEDesc via 
gelTexlFromDesc. dien it writes tliat text to the clipboard via 
writeStringToClipboard, then it cleans up and returns to 
handleSelection. 

getTexf From TH^ 

Any Lime you’re handling text selccii<7ns you need to get die 
selected text. getTexlFromDesc gets it as a CFString, 


72 


WRmNC. OwTRxntAi. Pur, ins for OS X 


Ma^Tech • January 2003 









www.reclstonesoftware.com/eggplant 



Listing 22: gelling text frcim an AEDesc 

gtiTcxiFrnmrX’sr 

static Boolean getTextFromDesc (const AEDesc *desc. 
CFStrin^Ref 'text. CFStrlngEncodlna eiicoding} 

I 

long len “ AEGetDeacDataSlze (desc); 
char *s: 

Bool nan flSticcnss “ falsf*: 
s ^ malloc (len + 1): 

if (s = mil) 

return (false); 

AEGeiDescDatfl (desc. s, len): 
fl [leni - no': 

flSuccess “ getCFStrtng (text. 

(coriBt char *) g* encoding]; 
free (s): 

return (flSuccess); 

I 


AEGetDescDataSize tells us how long the selected text is. It 
ihen all(x:iues u iKiffer lo gel thal text, then calls AEGelDescOata 
to [>ut it iiuo the liulTen El zercHenmnates the buffer so lliat its 
a C string. 

The fund ion ihen calls gelCFString to get a CFString based 
on the C siring it got from the AEDesc, 

Alter freeing the buffer (which Ls no longer needed) it 
retyrn.s inie if the Cl^tring wa,s created and false otherwise. 

gelCFString is a simple wrap]>er around 
CFStringCreateWithCString. 

Listing 23: getting a CFString from a C string 

gctl^fStririg 

static Boolean getCFStrin^ (CFStringRef 'siringToGet. const 
chat ’cStrinR. CFSttingEncoding encoding) 

I 

•strlngTotk*! - CFStringCcoatG¥lthCString 
(kCFAllocaLorBerault, cString. encoding); 
tetiirn ('stringToUet I" NULL) ; 

1 


writeStriiigToClipboard 

runCopyCommand then writes the text to the clipboard via 
writeSlringToClipboard, 

listing 24: wriling text to the diptoard 

writeSiri ngT< tCUptx >arxl 

static void wrlLoStrlngToClipbonrd (CFSttliigRcf s) 

[ 

ScrapEef scrap; 
char 'cString: 

if (IgetCString (ScString. s. kCFStringEncodingMacRoinan)) 
return: 

ClearCurrentScrap f): 

GeiCuxreniScrap (£rsci:ap): 

FutSctapPlavot: (scrap. kScrapFlavorTypeText, 
kScrapFlavorKaskHone. strlen (cStriug). 

(const void *) cString); 
free (cSiring); 

] 


Note tliat this seems a little mzy—in getTexlFromDesc we 
created a CFString from a G string, then in writeSlringToClipboard 
we turn around and gel a C strirtg from a CFString. Why? 
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Well, in ihe inieresLs of miuntuiniihility, I like luivlng just one 
function that gels the selected text, insle^id diere could lx: one 
ftinction thiit returns it ns a Ch'SEring and another tliat returns it 
as a C string. I prefer gelling a CFSiring because Ch'Sirings are so 
easy to manipuhue, and cliances are youVe going to want to do 
some Operation on the selected text. 

In lliis cjLse, however, we're not manipulating the selected 
text in any way, just writing it to the clipbtiard. 

Again, the writeStringToClipboard fiinciion could lake a C 
siring rather than a CKSlring, but my hel Is that most of the time 
ril have a CFString, since I use CFStrings so muc h. 

In other words, what Fve done is standardize on using 
CFStrings internally, so it’s only al the edges—when getting text 
from an AFDesc, writing text to the clipboard, or ailling the 
system function—wliere it’s sonielimes necessary to convert to 
or from a CFStringKef. (And, its yoiril note later in the Search 
with G(X)gle command, there are cases where no conversion is 
necessary as more and more APIs lake CFStrings, ) 

So writeStringToClipboard works in some ways like the 
callSystem command—it takes the CFStringRef and gets C 
string. A difference here Ls wliai it does with it—ii clears I he 
current scrap (the cliplx>ard), gels a reference to the curreni 
scrap, then write.s the C string as text to die cliptoard. Finally it 
frees tlte C string it got. 

'Ibat’s it for the Copy command. On to Search witli Google. 


Runaing the Search with Google comoiand 

'Ihis command gets tlie selected text then creates a search 
URL siring Irasecl on a base URL. Itie .search URL is then opened 
in one’s dehiult Web browser. 


listing 25: running the Search conmiand 

ninStiirdiCximinanil 

araric volet ninSparchCowand (conat AEDoac *dGscJ 
t 

CFStringRef selectedText. uriString; 

if (IgetTextFJTOHiDeee {desc, SrseiectedText, 
kCFStringEncodingHacRoinan)} 
return; 

if tiereateRnrodcdScarcbURLSiring 

(CFSTR (goog 1 eSeii tchtJRL). ej ec i edTeJtI, ^u11S t riiig) J I 

CFRelease (iseiectedText) i 

return; 

openlnBrowset (uriString); 

CFRelease (selectedText); 

CFReleajici (urlStr jirg); 

1 

As in runCopyCommand, ii calls gelTexlFromDesc to gci the 
selected text as a CFString. 

1'hen it creates the URL string to pass to the brow.ser by 
calling createEncodedSearchURLString. Then it calks 
openlnBrowser with tliai URL string to o[ieii it in the browser, 
Then it deans up and returns. 
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Encoding a tIRL string 

This function demonstrates some of tlie utility of CFStrings. 
h takes a siring like http://fooxom?q= as the base LlliL and a string 
like ’’some selected text'' as the searc'h arguments. It creates a 
string that a Web browser would understand, as in 
http://foo,com?c|==some+selected+text. 

In our case the base URI. is htip://www.gDogie.com/s€aFch?q= 
(defined in SampiePlugin.h), so the final URL string will kxjk 
sometiiing like http://www.google.com/search?q=some-»-selected+text. 

Listing 26; Encoding a URL string 

ca'aU’EiKxxIcdSiartiil JRlString 

static Boolean createRncodedStiarchURLString (CFStringRef 
baselIRLa CFStringRef searctiArgSt CFStringRef *dest} 

E 

CFStringRef urlString. urlStringPluKEncodndj 

urlString “ CFStrlngCreateWithFormat 
(kCFAllocatotOefauit, NULL* 
baseURL, searebArgs): 

if UrcplaceAn (CFSTR(^ U . CFSTR("lU. urlString. 
feurl S t rln gP 1 u sRn c oded)) \ 

CFRelease (urlString)j 
return tfalse): 

\ 

•dent = CFURLCreateStringByAddingPercentEscapes 
fkCFAlIocatorDefault. ttrlStringPlusEncoded> NULL, 

NULL, 

kCF S t r i n gEn cod i n g T SOI*3 tint): 

CFRelease (urlSttingPluijliiicodedl i 
CFRelease (urlString): 
return (Meat I- NULL) : 

I 

First it concatenates tlie base URL and the search args via 
CFStringCreateWithFormat. (Cocoa developers, note how similar 
this Ls to NSString's sthngWithFormal meiJK>dJ 

Then il calls replace All to replace spaces with + characters 
(which is what Web browsers and servers want us to do). 

Then it's necessary Lo tJRI-encodc tlie URL string- 
characters such a.s e and so on have to l>e converted to percent- 
encoding. CFURLCreateStringByAddingPercentEscapes does this. 
Finally it cleans up, and *dest is the encoded siring. 


Opening a URL in ihc default Web browser 

runSearchCommand then calls openlnBrowser to acuially 
open the URL in one’s default Web browser. 


Listing 27: opening a URL 

iiprnlfiBniwscr 

Static void openlnBrowser (CFStringRef urlString) 

[ 

CFURLRef tirlRef - CFURLCreateWithString 
(kCFAllocatorDefsult* urlString, NULL]; 

if (urlRef != NULL) [ 

LSOpenCFURLRef (urlRef. NULL]: 

CFRelease (urlRef): 

1 

» 


I'he sole parameter is a CFStringRef, the encoded URL 
string created in crealeEncodedSearchURLStnng. The system call 
for opening a URL in a browser w^ants a CKURLltef, which is 
created vk\ CFURLCreateWithString, (Cocoa developers: this is 
like NSURL^s URLWithString method.) 

Tiien the LauncliServices function LSOpenCFURLRef is 
called. This useful function also opens local l.TRLs, doing 
different things depending on wliai kind of URL it has. In 
this case iTs an HTTP URL, and so it opens the URL in the 
default browser. Note that the code doesn’t even know or 
care what the default browser is: tlie system handles it for 
us. (Cocoa developers note how this Is like NS Workspace’s 
openURL method J 

You can get more control over how the defaull brow^ser 
opens the URL by calling LSOpenFrom URL Spec—for instance, 
you can tell die browser not to come to the fnmL But in diis 
sample we use LSOpenCFURLRef fx^cause the default behavior 
is what we want anyway. 

After calling openlnBrowser, runSearchCommand deans up 
and returns contrc^l to handleSelection, which reiunis noErr. 

R<k>m for improvemrnt 

'Hiere some things this plugin could do Ixater—liul since 
this an ankle rather than a btxik. we'll lea\x* rliat up lo you. A 
couple obvious things: 

When getting text to write to the dipinjard or run a search 
on. it naively as.suiiies MucRonian text encoding, which is not 
tieccssarily the case, it's unlikely the a^.suh.s will lx satisfactory 
on, for instance, Japanese systems. 

Another issue is error re^[>orting—this plugin just faQs 
silently when sometiiing goes w-rong. At a minimum ii could 
write an error nie.ss^ige to the Console, But since most fxople 
don't leave their Console running, a better choice would be to 
disfilay a dialog box letting the user know tlie error* 

Bonus Tips 

Debugging 

1 nientioned earlier that printf. CFShow, and CFShowStr are 
useful for debugging—you can print to the Console to help you 
figure out what’s going on. 

Hut what if you w'ant to really debug—that is, set 
breakpoints and step ihniugh your ctxle? A plug-in isn’t an 
application, so you can’t just run and debug it as-ls. Heres 
what you do: 

From the Project tnenu diotxse New Custom Executabfe. Click 
the Set*** button in the dialog that appears. Choose an 
a]>plication that sitpports system contextual menus. Me, I always 
use Script Kditot; just I>et:ause it launches very <.{uickly on my 
niadiinc. CUek die Finish button. 
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Figure 3 Altaching cm axeauahle to the {Jltigin 


Then, IxT'ore debugging your plugin, sci ;i break]X>int 
somewhere—in examineConlext, for instance. To begin 
debugging, choose Debug Executable from the Debug menu. 
Script Rdiior (or whatever iipp yt>u chose) will buncli. 

Type st>me text in tin* app you diosc% select it, then Ctrl- 
click (t)r righi-click) on ihe selected text. Project Huiklcr's 
tiehuggCT should tome to the front with execution s!opy)ed at 
ytjur breakpoint, h'rom there you can debug as tuu mal 

(Unfortunately 1 have not figured out how to get this to 
work with the Finder, l)ut it w^urks very well for other apps.) 

St> your cycle Incomes like this: build your iilugin, delete 
the old version from your -/Library/Conlexlual Menu Items/ folder, 
copy the new' build to your Contextual Menu Items folder, 
t'hoo.se Debug Executable, tlien tlebug. btrher, rinse, re]7eat. 

Quitting apps 

Remenilxr that, when you rebuild a plugin and pul it in the 
Contextual M^u Items fokler, yem netxl iu tjuil any app you'ie testing 
with in ordcT ti> Idrce it reloiid tlw plugin. What’s tlie fastest way 
H> quit an a]^p that s not in front? Qrl<lick (or right-click) on its ici>n 
in tile l^cxk amJ clKxjse Quit fnsm the {X)[>uji menu. 

Tliis d<x:sn’t w'ork with the Finder. How'ever, you can 
enable a Quit menu item for the Finder so ihal ytiu can ty]>e 
Cmd-(J> in the Finder. In TerminaL type: defaults write 
com.appledfnder QuilMenultem Enabled 

Ytiu will have to log out then log back in for the changes 
to take effect. It later on you w'aai to disable tlie Quit menu item 
in the Finder, in Terniinul type: defaults write com.apple.finder 
QuilMenultem Disabled 

Quit the Finder and re-.start il (by clicking its icon in the 
Dock) and the Quit menu item will lie gone. 


Conclusion 

To summarize a few^ important points from this article: 

' To run a Unix ctanmanck call the system funtlion with a 
C string, with text that looks like what you would type on the 
command line. Rcnicmlx.T to add and escape quotes and $ 
chamaers as needed, 

- CFStrings are giXKJ to use tor lots <>f rea.sons, but the l>est 
one is that it makes string manipulation easy, 

’ Whether adding a command to the main c ontextual menu 
or to a submenu, youTe doing the .same I king, adding an item 
to an AEDescLisL There’s no difference. 

- tbere are other high-level routines like LSOpenCFURLRef 
that do things like ojx^n a URL in the defaiilt browser. If you find 
yourself doing things like WTiiing code to supi>ort different 
l>rowser.s, there’s a gexxi chance you’re w^orking way tocy hard. 
Pay special aUetilion to the CoreFoundalion and UmnchServices 
frameworks. Cocoa developers c an iKaicfit by looking at 
these frameworks, since ihere are useful functions there that 
have no Cocoa equivalent but that work with NSSlrings and 
NSURLs and so on. 

- printf, CFShow, and CFShowStr are useful for debugging— 
but, even belief you can truly debug a plugin by attaching an 
execyialile and setting a breakpoint. 

- Rememlx^r to quit apps you re testing with after mbiiilding 
your plugin. You can even enable a Quit item for the Finder via 
file defaults Temiinal command. 

Thanks to*.. 

For review and feedback for this article, thanks to jim 
C(HTciu» Quentin l>. Camicelli, and Ceorge Warner. Any 
lemaining errors or cxldiiies are mine, 

ReFERI'NCI-S 

• Apple sample code: http://developer.apple.com/ 5 amplecode/ 
Sampie_Code/Human_lnterface_Toolbox/SampleCMPIygln.htm 

• (jojeFounitation Plugin Services: htlp://d€ve!oper.apple.a)nT/techpubs/ 
macosx/CoFeRxindation/PluginSefvices/Plyg_in_.SewkesConcTask/incfexht 

• (>>reFoundation String Services: littp://developer, apple.com/techpLibs/ 
macosx/ComFDundation/Sti1ngSeTvices/STring_Servi{:es_ConcTaslc/index.html 

• CoieFoundaiion URl* Services: http://devetoper.apple.com/techpubs/ 
macosx/CoreFoundaton/URLServices/URLServices/index.html 

• Contextual Menu Workshop is a free framework for creating 
OS X contextual menus: http://homepage.mac,com/tkukiei/ 
cmworkshophtml 
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2. Cut Corners 


^ For developers under pressure to manage source code and do more in less time. 
Perforce'^ Fast Software Configuration Management System is the must-have tool 


With rival SCM systems, the only way to 
quicken the pace is to cut comers - but in the 
long run you pay the price with missed 
deadlines, uncertain contents, buggy releases 
and no way back to previous builds. 

With Perforce, the fast way is always the 
right way. Install it fast, learn it fast, execute 
operations fast. With other SCM systems, 
developers face an unpleasant choice: 
do it the right way or do it the fast way. 

Perforce's speed and reliability mean fast is right. 
See how Perforce compares with other 
leading SCM systems at 
htt p ://www. pe r f orce-CO m/perf orce/revi 0 ws. htm I 


Run at hiil speed even with hundreds of users 
and m////cPos of files. At the core of Perforce Jles 
a relational database with well-keyed tables, 
so simple operations can be accomplished in 
near-^ero time. Larger operations (like labeling 
a release and branching! are trar^slated into 
keyed data access, giving Perforce the scalability 
that big projects require. 

Work anywhere. Perforce is efficient over high- 
latency networks such as WANs, the Internet and 
even low-speed dial-up connections. Requiring 
only TCP/lP| Perforce makes use of a well-tuned 
streaming message protocol for synchronizing 
client workspace with server repository contents. 


Develop and maintain multiple codelines. 
Perforce Inter-File Bra nching"" lets you merge 
new features and apply fixes between codelines. 
Smart metadata keeps track of your evolving 
projects even while they develop in parallel. 

Truly cross platform. Perforce runs on more than 
50 operating systems, including Windows and 
nearly every UNIX^ variation, from Unux and 
Mac OS' X to AS/400 and more. 

Integrate with leading lO£s and defect trackers: 
Visual Studio.NET% Visuai C++ , Visual Basic*, 
JBuilder*, CodeWarrior, TeamTrackBugzilfa’^, 
Control Center;, DevTrack- packages, and more. 


Perforce 

SOFTWARE 

Fast Software Configuration Management www.perforce.com 


Download your free 2-u$er, non-expiring, full-featured copy now from www.perfbrce.com 
Free (and friendly) technical support is on hand to answer any and all evaluation questions. 
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We're Easier. 

Create anything from prototypes to full professional applications. Just drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your stuff great — 
your ideas! REALbasic creates native compiled applications for Macintosh, Mac OS X and Windows 
without platform-specific adjustments. It's the powerful, easy-to-use tool for creating your own 
software. Each version of your software looks and works just as it should in each environment. 

Complex problems shouldn't require complex solutions. The answer is REALbasic. 


3 REALbasic4.5 


NEW VERSION 


Come see us at Macworld in MacTech Central! Download a free demo, www.realbasic.com 













